1.
Introduction
mlrpt is a non-interactive command-line version of glrpt, an
integrated application for Receiving, Decoding and Saving LRPT
Images from the Russian Meteor-M type of Weather Satellites. mlrpt
supports reception through the now very popular RTL-SDR receiver
dongles, available cheaply from many sources. As of version 1.2,
mlrpt supports reception with the Airspy R2 and Mini SDR
receivers.
Usage:
mlrpt [-c config-file -f frequency -s hhmm-hhmm -t sec -qihv]
-c: Specify name of Satellite-specific configuration file.
-f: Specify SDR Receiver Frequency (in kHz).
-r: Specify Image Rectification: 0 = None, 1 = W2RG, 2 = 5B4AZ.
-s: Start and Stop Time in hhmm of Operation.
-t: Duration in min of Operation.
-q: Run in Quite mode (no messages printed).
-i: Invert (flip) Images. Useful for South to North passes.
-h: Print this usage information and exit.
-v: Print version number and exit.
2. FeaturesPer-Satellite configuration
files
With the arrival of a new Meteor-M2 satellite, it is now necessary
to have separate configuration files for different satellites.
mlrpt now requires one default configuration file and one such for
each satellite of interest. The default file may be a link to one
of the satellite-specific files. The required configuration file is
specified by the -c command line option: mlrpt
-c<config-file-name>. Configuration files are assumed to be
in mlrpt's working directory and only the file name need be
supplied: mlrpt -c Meteor_M2-2.cfg will cause mlrpt to look for a
configuration file named Meteor_M2-2.cfg in
/home/<user-dir>/mlrpt/ and use this to configure itself for
that satellite.
It is necessary for at least one default configuration file to be
present in mlrpt's working directory, named default.cfg. This can
be a link to a preferred satellite's configuration file.
SDR Receiver
set-up
mlrpt automatically sets up the SDR Receiver, specified in the
configuration file, for the required parameters (Center Frequency,
Sampling Rate, Butterworth LPF cut-off etc) for correct
operation.
Normalization of
images
mlrpt performs simple (linear) Histogram Normalization of the LRPT
images to enhance Contrast and Luminance range. If normalization is
not desired, it can be disabled in the
/home/user/mlrpt/<config-file> configuration file.
C.L.A.H.E.:
Contrast Limited Adaptive Histogram Equalization algorithm by Karel
Zuiderveld, from "Graphics Gems IV", Academic Press, 1994, Computer
Vision Research Group, Utrecht, The Netherlands. This provides
excellent regional Enhancement of Contrast, but it has to follow my
own simple Histogram Normalization function because this is set up
to ignore the occasional black stripes that Meteor-M2 seems to
transmit in the images.If CLAHE equalization is not desired, it can
be disabled in the /home/user/mlrpt/<config-file>
configuration file.
Rectification of Tangential
Distortion:
Rich Griffiths W2RG has contributed code to rectify the Geometric
distortion present in raw images of Meteor-M satellites. This
distortion is caused by the ever increasing physical length of
image pixels due to the geometry of the satellite's scanners
(tangential distortion). The Earth's curvature also contributes to
this distortion and now mlrpt has built-in code to correct this
deficiency.
Since version 1.7, I have added my own take on rectifying Meteor-M raw images. The code is similar to W2RG's code, except that the creation of added pixels, needed to "stretch" the image, is done by linear interpolation rather than filling gaps between pixels of the rectified image. Either one of the rectification functions (or none) can be specified in the configuration files or by a command line option.
Pseudo-colorization of
images
mlrpt can enhance the colorization of the combined pseudo-color
image by detecting watery areas in a specified APID image and
enhancing the blue RGB channel. It can also enhance cloud cover by
detecting bright areas in the blue channel image and equalizing the
RGB channels. If colorization is not desired, it can be disabled in
the /home/user/mlrpt/<config-file> configuration file.
Inversion (flipping) of
images
mlrpt can perform 180 degree Rotation (Flip)) of the APT images if
the -i command line option is given. This is useful for righting
the inverted images produced by the South-to-North passes of the
satellites.
3.Quick
Start
First navigate (cd) to the directory you have downloaded mlrpt.
Usually this will be Downloads/ in your home directory.
cd ~/Downloads/ tar jxvf mlrpt-*.*.tar.bz2 cd mlrpt-*.* ./autogen.sh ./configure make sudo make install
This should install the "mlrpt" binary in /usr/local/bin. The mlrpt's documentation will be installed in /usr/local/share/doc/mlrpt/ and its working directory in /usr/local/share/examples/mlrpt. The user should then create mlrpt's working directory /home/<user-dir>/mlrpt/ and copy the files in /usr/local/share/examples/mlrpt/ to this directory. If all goes well, you should be able to start mlrpt just by typing mlrpt, without any command line options, in the console. For quiet operation, start with mlrpt -q. To quit mlrpt and save any images that were received (to /home/user/images), type Ctrl-C (user interrupt) in the console. Otherwise mlrpt will terminate when its internal timer has completed. Default timeout is specified in the ~/mlrpt/<config-file> configuration file.
While mlrpt will work with its default configuration, it can now be directed to use a satellite-specific configuration file by using the -c command line option, e.g. mlrpt -c M2-1.cfg will direct mlrpt to use Meteor-M2-1's specific configuration file. The user will need to go through the configuration files and edit the settings according to each satellite's parameters, mainly the LRPT Transmitter frequency, the Symbol Rate and the Image Channels currently in use.
Other settings that might need editing is the Synthesizer Frequency Error correction factor where you should enter your SDR Receiver's synthesizer error. If in doubt, just leave it as is (0). Also the Duration in seconds of the image decoding operation, the default of 900sec (15min) may be too long when using fixed antennas like QFHA or turnstiles. However, this will not affect successful reception of images.
4.
Compilation
Please note that I use Void
Linux AMD64 which is a "bleeding edge" type distribution, so
there may be compilation and/or run time difficulties if you are
using a relatively old distro. This is mostly true of the basic
dependencies like the SDR API development libraries
(librtlsdr-devel and lib airspy-devel).
To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.
Running "make" in the package's top directory should produce the executable binary in src/. Running "make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the mlrpt working directory and default configuration file into the user's home directory. This will have to be edited by the user as required. There is also this hypertext documentation file which you can copy to a location of your choice.
5. Usage and command line
options
mlrpt [-c config-file -f frequency -s hhmm-hhmm -t sec -qihv]
-c: Specify name of Satellite-specific configuration file.
-f: Specify SDR Receiver Frequency (in kHz).
-r: Specify Image Rectification: 0 = None, 1 = W2RG, 2 = 5B4AZ.
-s: Start and Stop Time in hhmm of Operation.
-t: Duration in min of Operation.
-q: Run in Quite mode (no messages printed).
-i: Invert (flip) Images. Useful for South to North passes.
-h: Print this usage information and exit.
-v: Print version number and exit.
6. Operation
Setting up working directories:
Before mlrpt is used to receive images, it is important to
understand how the resulting image files are named and saved: mlrpt
generates file names based on the channel number and the current
date and time and stores image files in its
/home/<user-dir>/mlrpt/images/ directory. The image file
names are created from a base string of the format ddMonyyyy-hhmm
where dd is the day number, Mon is the month name, yyyy is the year
and hhmm the current time (UTC) in hours and minutes. To this, the
LRPT image channel number is appended and then the extension .jpg
or .pgm or .ppm is also appended, e.g. 05Sep2018-0728-Ch0.pgm is a
Channel 0 image file that was saved on September 5 2018 at 0728
UTC.
7. Bugs and annoyances:
I have fixed whatever bugs I came across testing mlrpt but there
may be some hiding, waiting for the right conditions to appear.
This is a beta release so I would appreciate bug reports from any
users.
8.
Acknowledgments:
This application was put together by modifying and adapting two
independent projects:
The LRPT Demodulator is based and Davide Belloli's (dbdexter-dev)
"meteor_demod" project on GitHub, and the LRPT Decoder is based on Artem
Litvinovich's (artlav) "meteor_decoder" project, also on GitHub.
My sincere thanks go to both developers for producing the
fundamental code needed to receive and decode LRPT images from the
Russian Meteor-M class weather satellites. And to the great ideal
of Free and Open Source software development model for enabling
this application to be built!
The Contrast Limited Adaptive Histogram Equalization (CLAHE) algorithm is based on code by Karel Zuiderveld, from "Graphics Gems IV", Academic Press, 1994, Computer Vision Research Group, Utrecht, The Netherlands
The built-in JPEG compressor code is based on the experimental JPEG compressor Codename "Nether Poppleton" by Kornel Lesinski (c) 2013. All rights reserved. Based on code by Rich Geldreich. The original was in C++ but I translated it to C as it is the programming language I use.
The initial Image Rectification code was adapted from the original "rectify-jpeg" tool produced by Rich Griffiths W2RG. Later I added my own take on image rectification so the mlrpt has two such functions for the user to choose from!
9. Version history:Version 0.2-alpha: After editing and modification, I
incorporated the LRPT Demodulator code created by Davide Belloli
"debdexter-dev" and made it demodulate LRPT signals from the live
stream supplied by the SDR Receiver.
Version 0.3-alpha: After editing and modification, I incorporated the LRPT Decoder code created by Artem Litvinovich "artlav" and made it decode images from the live streaming QPSK soft symbols produced by the LRPT Demodulator.
Version 0.4-beta: Once mlrpt was able to receive, demodulate and decode LRPT images successfully, I considered it ready for a beta status but did not release it as I was mainly testing the graphical glrpt.
Version 0.5-beta: Added built-in support for saving the monochrome (Greyscale) channel images as JPEG files. The JPEG compression code is open sourced and was released by Moodstocks SAS. Copyright is owned by the company. Please note that if the pseudo-color combined image creation is enabled, it can only be saved as a PPM file.
Version 0.6-beta: Fixed minor bugs in the code that saves images in JPEG format.
Version 0.7-beta: I have added the (slightly modified) C code of the "Contrast Limited Adaptive Histogram Equalization" algorithm by Karel Zuiderveld, from "Graphics Gems IV", Academic Press, 1994, Computer Vision Research Group, Utrecht, The Netherlands. This provides excellent regional enhancement of contrast, but it has to follow my own simple Histogram Normalization function, which is set up to leave behind the occasional black stripes that Meteor-M2 seems to transmit in the images.
Version 0.8-beta: Fixed a buffer overrun bug in the Histogram Normalization function reported by Coverity Scan.
Version 0.9-beta: Fixed some minor bugs reported by LLVM's clang-analyzer tool. Added options to the config file, to specify for each channel image a range of values to which the image's luminance will be mapped before combining into a color composite image. This can be used to adjust the color balance of the composite image. Also added options to specify the range of pixel values in the Blue image that will enhanced if Pseudo Colorization is enabled. This helps to improve the color of watery areas (seas and lakes) since Normalization darkens these areas by stretching the Histogram.
Version 1.0: Added an new item in the /home/user/mlrpt/<config-file> configuration file, to specify the directory to save received images in. I am removing the beta since mlrpt has been tested by third parties and been debugged.
Version 1.1: Added an new item in the /home/user/mlrpt/<config-file> configuration file, to specify the Blue channel pixels value above which it is assumed that they are in a cloud area. This is used in the pseudo-colorize mode to enhance cloud color.
Version 1.2: Added support for the Airspy R2 and Mini SDR receivers, using the native lib airspy driver API. Added a new option in the mlrpt's configuration file to enable saving of images as decoded from the satellite and without image processing (Normalization and C.L.A.H.E. contrast enhancement). Modified data transfer method to a double-buffered method to improve overall performance. Added a new option in mlrpt's configuration file to specify Manual Gain Control of the SDR Receiver, in the range 0-100%. Default is 90%. A value of 0 specifies Auto Gain Control.
Version 1.3: Modified the RRC Filter code to reduce processor workload by about 5-6%. Not a very substantial result but still worthwhile for lower-powered computers.
Version 1.4: Fixed some bugs reported by Tim Kunze that
were preventing compilation, if one of the supported device drivers
(libairspy or librtlsdr) was not installed. Also replaced the
explicit_bzero() library function with memset() since the former
was not available in Tim Kunze's distribution (and possibly
others').
Added an additional option in the mlrpt's configuration file to
specify the APID for an image channel to invert its palette, e.g.
change the luminance values from black-to-white into
white-to-black. This is useful for the Infra-red channel as clouds
(that are cold) are shown as black, and land that is warmer as
white
Version 1.4.1: By user request, the acceptable receiver filter bandwidth can now be between 100kHz and 200kHz.
Version 1.5: Added code to rectify geometric distortion in present in raw Meteor-M images. This code has been extracted and adapted from the code of rectify-jpg, contributed by Rich Griffiths W2RG.
Version 1.6-beta: With the arrival of a new Meteor-M2 satellite it is now necessary to have separate configuration files for different satellites. mlrpt now requires one default configuration file and one such for each satellite of interest. The default file may be a link to one of the satellite-specific files.
I have added my own take on rectifying Meteor-M raw images. The code is similar to W2RG's code, except that the creation of added pixels, needed to "stretch" the image, is done by linear interpolation rather than filling gaps between pixels of the rectified image. Either one of the rectification functions (or none) can be specified in the configuration files or by a command line option.
Davide Belloli (dbdexter-dev) has produced a new version of his "meteor_demod" tool, a demodulator for Meteor M2 signals. This new version now supports demodulation of both QPSK and OQPSK signals and I have now incorporated it in mlrpt. Unfortunately artlav's image decoder code "medet" does not support OQPSK, so mlrpt cannot decode such signals (from Meteor M2 2 for example) at this time. Hopefully some solution to the problem will be found sometime soon, especially if artlav responds to such requests made on Github.
Artyom Litvinovich (artlav) has now produced a new version of "medet" which supports decoding of OQPSK signals from Meteor M2-2, in both 72k and 80k (interleaved) symbol rates. I have incorporated the changes to mlrpt but have not yet been able to get the decoder to work with the interleaved 80k symbol rate format. For this reason I am releasing mlrpt, provisionally, as version 1.6-beta, for testing.
I have managed to get the decoder to work with the 80k Interleaved OQPSK mode but the code is still incomplete and results in broken images. However, this is a hopeful sign for me, that I may later manage to fix the adaptation of the original decoder. Problem - Meteor M2-2 has switched to the 72k sym rate mode! (Again).
Version 1.6.1-beta: I made a number of changes to the M2-2 80k symbol-rate demodulator and de-interleaver, to complete the adaptation of artlav's meteor-decode (medet) tool. Yet again, M2-2 changed to 72k mode just as I was ready to test mlrpt. However, I was able to test it using pre-recorded raw I/Q data and unfortunately the images produced are broken by wide black bands and so far have not been able to find out why. I suspect the loss of sync detection and if I can, I will try to do something about it.
Version 1.6.2-beta: I fixed a bug in the code that "fixes" the Differential Offset QPSK modulation scheme of Meteor M2-2, which in rare circumstances could cause an off-by-one array access, resulting in a segmentation fault.
Version 1.6.2: Meteor M2-2 now seems to be on the 72k DOQPSK mode so I cannot do any more testing on the 80k Interleaved mode. I have only made some changes to the installer, as described earlier, and I am calling this my latest release version.
Version 1.6.3: Made some changes to the Costas PLL loop to improve phase lock capture and stability.
Version 1.6.4: After a report by Gianpi IK1TTD, I edited the configuration files for the proper default SDR device (RTL-SDR) and arranged for the mlrpt code to abort on some configuration errors.
Version 1.7: Changed the buffering system of the DSP samples stream from double buffering to a ring buffer, because the producer/consumer indices were going out of sync, especially when the signal processing and image decoding functions were slowed down by processor workload. The ring buffer arrangement now contains code to re-synchronize the producer/consumer indices when they are out of sync, so that DSP data is not lost and artifacts in images are not created.
Removed the sample interpolation code from the demodulator since it is not really needed. The change in effective sample rate to the demodulator is compensated in the initialization functions of the SDR driver code.
Arranged for the image decoder to begin decoding images when frasme detection takse place. The decoder will no longer wait for the PLL to lock before starting to decode.
Version 1.7.1: Changed the installation commands in Makefile.am so that all the relevant files (desktop file, application pixmap, configuration file, executable binary etc) are installed under any location specified to the configure script by the --prefix= option. Also modified the program so that on first start up after installation, the application will create its working directory by copying files from the relevant directories under the installation prefix.
10. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.