glrpt User Manual

1. Introduction
   • Usage
2. Features
   • Per-Satellite configuration files
   • SDR Receiver set-up
   • Normalization of images
   • Contrast Limited Adaptive Histogram Equalization
   • Rectification of Raw images
   • Pseudo-Colorization of images
   • Inversion (flipping) of images
3. Quick Start
4. Compilation
5. Command line options
6. Operation
7. Bugs and annoyances
8. Acknowledgments
9. Version history
10. Copying

1. Introduction
glrpt is an interactive X/GTK+-3 GUI integrated application for Receiving, Decoding and Displaying LRPT Images from the Russian Meteor-M type of Weather Satellites. As of version 1.8, glrpt supports reception through whichever SDR Receivers are supported by the SoapyAPI library. Currently it has been tested with RTL-SDR and Airspy devices.

Usage: glrpt [-hv]

-h: Print this usage information and exit.

-v: Print version number and exit.

2. Features
glrpt can decode images in real time as they are received from the satellite and display them incrementally as they form, slow-scan TV fashion. The images displayed in the glrpt window are scaled down by a factor specified in the ~/glrpt/glrptrc configuration file. The APID channel images stored in ~/glrpt/images/ are full sized and are saved either in the PGM (Portable Grey Map) format or JPEG format. A new JPEG compression code in glrpt allows both monochrome and color images to be saved as good quality jpeg files. Please note that the images/ directory can be a relative link to some other directory of user's choice.

Per-Satellite configuration files
With the successful launch of Meteor-M2-2, I have modified glrpt so that it can now configure itself by reading per-satellite configuration files. These are expected to be in glrpt's working directory (/home/<user-dir>/glrpt/) and also have a ".cfg" file extension. These configuration files are almost identical to the original glrptrc file, except that the list of satellite names and frequencies at the top of glrptrc is now replaced by just the frequency, in kHz, of the satellite's LRPT transmitter.

At start-up, glrpt searches its working directory for files with the ".cfg" extension and uses the file name, bar the extension, to fill the "Select Satellite" menu item. Hence a config file "Meteor-M2-2.cfg" will appear as "Meteor-M2-2" in the Select Satellite menu item. The first menu entry is used as the default at start up to allow glrpt to properly configure itself and present the GUI.

SDR Receiver device set-up
Using the SoapySDR API, glrpt automatically sets up the required Device parameters (Center Frequency, Sampling Rate, Gain control mode, Butterworth LPF cut-off etc) for correct operation.

Normalization of images
glrpt performs simple (linear) Histogram Normalization of the LRPT images to enhance contrast and luminance range. Please note that this results in all channel images' luminance (pixel value) range to be "stretched" to the full range of 0-255, thus affecting the colors of the combined color image. This function is set up to ignore full black pixel values, so that the occasional black stripes that Meteor-M2 seems to transmit in the images do not affect normalization. If normalization is not desired, it can be suppressed by deactivating the "Normalize Images" check menu item.

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, which is set up to ignore the occasional black stripes that Meteor-M2 seems to transmit in the images.

Rectification of images:
Rich Griffiths W2RG has contributed code to rectify Meteor-M images (correct tangential geometric distortion). The original code is for a command line tool that can open Meteor JPEG images produced by glrpt, rectify the tangential distortion and then save the corrected images back to a JPEG file. Here I have adapted the inner working parts of this tool into glrpt so that now images are rectified by glrpt before being saved. Rectification is an option that can be selected from the main pop-up menu and also specified in the glrptrc configuration file.

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
glrpt can enhance the Colorization of the Combined pseudo-color image by detecting watery areas in the blue channel image (they become the darkest areas after Normalization), and raising the "floor" values of this channel to brighten blue areas (seas and lakes). glrpt can also enhance cloud cover by detecting bright areas in the blue APID image and using the pixel values in all three colors of the combined image. If colorization is not desired, it can be disabled by deactivating the "Pseudo Colorize" check menu item.

Inversion (flipping) of images
glrpt can perform 180 degree Rotation (flip)) of the APT images if the "Invert Images" check menu item is checked. This is useful for righting the inverted images produced by the South-to-North passes of the satellites.

4.Quick Start
Open a console and navigate (cd) to the directory where you downloaded glrpt. Usually this will be Downloads/ in your home directory.

cd ~/Downloads/
tar jxvf glrpt-*.*.tar.bz2 
cd glrpt-*.*
./autogen.sh 
./configure 
make
sudo make install

This should install glrpt in /usr/local/bin. It should also install glrpt.desktop in /usr/share/applications, glrpt.svg in /usr/share/pixmaps, the short glrpt.1.gz manual in the man1 directory and this glrpt.html document in /usr/local/share/doc/glrpt. The default configuration files in glrpt/ will be installed in /usr/local/share/examples/glrpt/ together with the glrpt.glade GUI description file. The configuration files and the glade GUI file should be copied to glrpt's working directory in /home/<user>/glrpt. It is also necessary to either provide a folder named "images" in glrpt's working directory or a link named "images" to some other directory of the user's choice.

If all goes well, you should be able to start it just typing: glrpt in the console. It should also appear in your Desktop's launcher menu somewhere, normally in Amateur.

Glrpt may work with its default configuration files, however it is necessary to review at least a few settings and edit as needed. More details of config file entries further down.

To start reception, right-click in the large image preview display window and activate the "Start Receiver" menu item. Once you get the green PLL lock "LED" indication, activate the "Decode Images" menu and if signal is good, you will get the green FRM (Frames Received) LED indication. The three decoded images will be displayed progressively as they are received. As of version 2.4, glrpt can be started and stopped by activating the START Toggle Button in the SDR Receiver Control frame.

When the pass is over, it is necessary to disable the "Start Receiver" menu item to signal glrpt that you are finished so that it will process the images and save them (full size) in ~/glrpt/images/. Same will also take place if the START Toggle Button is disabled.

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 GTK+-3, Glade-3 and the SoapySDR library with its development files (headers).

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 install glrpt in /usr/local/bin. It should also install glrpt.desktop in /usr/share/applications, glrpt.svg in /usr/share/pixmaps, the short glrpt.1.gz manual in the man1 directory and this glrpt.html document in /usr/local/share/doc/glrpt. The default configuration files in glrpt/ will be installed in /usr/local/share/examples/glrpt/ together with the glrpt.glade GUI description file. The configuration files and the glade GUI file should be copied to glrpt's working directory in /home/<user>/glrpt. It is also necessary to either provide a folder named "images" in glrpt's working directory or a link named "images" to some other director of the user's choice.produce the executable binary in src/.

5. Command line options
glrpt's command line options are:

-h: Print this usage information and exit.

-v: Print version number and exit.

6. Operation
Setting up working directories:
Before glrpt is used to receive images, it is important to understand how the resulting image files are named and saved: glrpt generates file names based on the channel number and the current date and time and stores image files in its ~/glrpt/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 .pgm or .ppm is appended, e.g. 05Sep2018-0728-Ch0.pgm is a Channel 0 image file that was saved on September 5 2018 at 0728 UTC.

Before running glrpt, it may be necessary to customize some entries in the ~/glrpt/glrptrc configuration text file in your home directory. These are the items that may need editing:

• As of version 2.4, glrpt now supports the use of per-satellite configuration files rather than one single glrptrc file. This allows the specification of different parameters for demodulating and decoding images from more than one Meteor M2 type of weather satellite or for more than one modulation mode of some satellite. This feature became useful with the launch of Meteor M2-2 which seems to switch between 72k sym-rate/DOQPSK and 80k sym-rate/IDOQPSK. So the following config entries may be set per-satellite and per-mode as needed.
• The SoapySDR device driver name or "auto". For RTL-SDR devices the driver name is "rtlsdr" and for Airspy devices the driver is "airspy". If "auto" is specified, then glrpt will auto-detect the SDR device and it will set up required parameters automatically.
• The SoapySDR device index. This is 0 for first detected device, 1 for the second etc.
• Low Pass Roofing Filter Bandwidth. This should be more than 100kHz and less than 200kHz for sanity checking. Default 110kHz (1.5x Symbol Rate) and this is probably the narrowest usable bandwidth.
• The Setting of the "Manual Gain" slider to be used in Manual mode. A setting of 0 signifies Automatic Control and any other setting up to 100, signifies Manual Control of Receiver gain
• The Synthesizer Frequency Error correction factor (default is 0) This is an integer number and it is Parts per Million (ppm).
• The Satellite's LRPT Transmitter's Frequency in kHz. Default is 137100.
• The duration in sec of the image Receiving and Decoding Operation. The default is 900 sec but it is usually too long (15 min) unless a rotatable beam antenna is used. Normally about 400-500 sec is reasonable.
• The scale factor to be used to reduce the size of LRPT images in the image display window of glrpt. The default is 5 but 4 may also be used when screen size allows.
• The RRC (Raised Root Cosine) Filter Order, normally 64. A value of 32 may be used if 64 results in heavy processor loading.
• The RRC Filter alpha factor. Default is 0.6 and should not normally be changed.
• Initial Costas PLL Loop Bandwidth in Hz. Default is 100.
• Costas PLL In-Lock Phase Error Threshold. Below this the PLL will be in Locked mode. The PLL Unlocked Threshold will be set at +5% above this. The actual value will depend on Receiver noise levels and Antenna performance. It should be selected so that the PLL Locked indication should just be off with no signal. Default is 0.82.
• QPSK Modulation Mode: 1 = QPSK 2 = DOQPSK (Differential Offset QPSK) 3 = IDOQPSK (Interleaved DOQPSK). For Meteor M2, this is QPSK. For Meteor M2-2, if in 72k Symbol Rate then its DOQPSK and if in 80k Symbol Rate then its IDOQPSK.
• Symbol Rate of the Satellite's QPSK Transmission, in Sy/s. Default is 72000.
• Demodulator Interpolation factor. Default is 4 and need not be changed.
• Decoded Image Output Mode:
  1 = Output a combined APID channels pseudo-colorized image.
  2 = Output individual monochrome images of APID channels. This is the default.
  3 = Output both Combined and Channel Images (Default).
  
• File type for saving monochrome and colorized images.
  1 = Save as jpeg.
  2 = Save as PGM file.
  3 = Save as both.
• JPEG compression quality factor (percent). Default is 85%.
• Save Raw images as produced by the LRPT decoder. 0 = no, 1 = yes. Default is 0 (No).
• Image Normalization (Stretches image contrast).
  0 = no, 1 = yes. Default is 1.
• C.L.A.H.E. (Contrast Limited Adaptive Histogram Equalization). Provides excellent Regional Contrast Enhancement.
  0 = no, 1 = yes. Default is 1.
  The Image Normalization option above must also be enabled for this to have effect.
• Rectification of images. Enables correction of tangential geometric distortion that is present in raw Meteor-M images.
  0 = None, 1 = Use the W2RG algorithm, 2 = Use the 5B4AZ algorithm. Default is 1.
• Pseudo-colorize images: Does some speculative colorization of the combined pseudo-color image.
  0 = no, 1 = yes. Default is 1.
• APID's of available Image Channels from the Satellite. They will be used to produce glrpt's "image channels" 0, 1 and 2.
• glrpt's image channels to combine in order to produce the pseudo-color image. These channel numbers will be used for the red, green and blue channels of the color image. Normally 0 1 2.
• Image APIDs to invert their palette. This is normally useful for the Infrared images were cold is dark and hot is white. Three comma-separated entries are needed. 0 per place will disable this option. Default is 67, 68, 69.
• Range of pixel values to use when combining channels, to produce a reasonable color balance in the combined color image. Values must be between 0 and 255.
• When using the optional Pseudo-colorize function of glrpt, the pixel values of the Blue channel image are increased so that they are in the range specified below. This helps because Histogram Equalization darkens the parts of the Blue Channel image that are watery areas (seas or lakes).
  
• Blue Channel minimum pixel value. Must be between 0-255. It is also the Blue Channel pixel value below which pixel values are mapped into the range between these two values.
• Blue Channel maximum pixel value when mapping pixel values into the range between these two values. Must be higher than the above minimum but less than 255.
• Blue channel cloudy area pixel value threshold. In pseudo- # colorize mode, pixels with a value higher than this will be # assumed to be cloudy areas and the RGB values in the combo # color image will be made all equal to the blue channel pixels.

2. To the right of the above viewer, there is a collection of frames with various control and display widgets:

• SDR Receiver Control Frame:
  
  • The "SDR Receiver" widget displays the type of SDR device that is in use the reception of the Satellite.
  • The START toggle button can be used to start the Receiver, Demodulator and Decoder functions. The "LED" indicator icon shows the status of the SDR receive: Green indicates that it has been started successfully and Red indicates an error condition.
  • The "BW-kHz" entry displays the current Roofing Filter bandwidth in kHz but it can also be used to enter a new bandwidth value. Please note that this filter determines the bandwidth of the SDR Receiver and must be at least about twice the Symbol Rate of the LRPT transmission (currently it is 72 kS/s).
  • The "Freq-kHz" entry displays the SDR Receiver's current center frequency but it can also be used to type in a new frequency (in kHz).
  • The Manual Gain slider can be used in the Manual Gain Control made to set the Gain of the SDR Receiver. The scale is calibrated from 0 to 100% but glrpt translates this to the available range of Gain of the Receiver. The default Manual Gain can be specified in the /home/user/glrpt/glrptrc configuration file. A value of 0 signifies Auto Gain Control. Any other value up to 100 signifies Manual Gain Control and sets the Gain slider.
  • The Man and Auto Radio Buttons can be used to select Manual or Auto Gain Control. The Gain slider setting is saved internally and restored when Manual Gain is selected.
• Receiver Status Display Frame:
  
  • The "Costas PLL Phase Error" widgets indicate the average phase error in the Costas PLL. Currently a value of 0.26 is chosen to indicate Locked and 0.28 to indicate Unlocked condition.
  • The "PLL Freq" widget indicates the effective deviation in Hz of the Receiver's center frequency from the Satellite transmitter's carrier frequency. If both the Receiver's center frequency and the transmitter's carrier frequency were precise, this would indicate the Doppler shift of the satellite's frequency.
  • The "Decoded Signal Quality" widgets indicate the signal quality level as calculated by the decoder code. Best signal quality is 100%.
  • The "Packets" widget shows a count of packets successfully decoded and their proportion, as a percentage, to the total packets received. In ideal conditions this should be 100%!
  • The "Auto Level Control Gain" widgets indicate the loop gain of the automatic samples magnitude control system. This scales incoming sample values so that a samples stream with fairly stable amplitude is fed to the Demodulator code..
  • The "Onboard T" widget shows the Satellite's on board time as included in the LRPT packets.
  • The "ALC Input Signal Level" widgets display the average magnitude of the samples stream, incoming from the SDR receiver device.
  • The "FRM" "LED" icon indicates a "valid packet decoded" (green) or a "packet lost" (red).
  • The "PLL" "LED" icon indicates a "PLL Locked" state (green) or a "PLL Unlocked" state (red).
• The FFT Spectrum (Waterfall) and the QPSK Constellation frames:
  The Spectrum Display shows the output of the Integer FFT function that computes the Fourier transform of the SDR Receiver's I/Q signal output. The display is color-coded for easy viewing and covers a bandwidth about twice the Symbol rate.
  The QPSK Constellation display shows the output of the Costas PLL which, when locked, provides a synchronized QPSK signal consisting of pairs of I/Q values. When the PLL is locked, its output can be seen to be grouped in the four box sections of the display.
• The Glrpt Messages Frame:
  This frame contains a text view widget in which glrpt prints various status messages for the user. These can be progress information, warnings or error messages.

3. A pop-up menu: This appears after a right-click on the scaled image display in the main window. Some of the options in this menu can be set by default in the ~/glrpt/glrptrc configuration file. This menu has the following items:

• Start Receiver: Checking this menu item starts the SDR Receiver and the LRPT Demodulator. This results in the Spectrum and QPSK Constellation displays to activate so that the satellite's signal can be monitored. Please note: It takes a few seconds to initialize reception from the SDR Receiver and during this period the pop-up menu is blocked to avoid glitches
  Un-checking this menu item stops the SDR Receiver, the Demodulator and the relevant displays. If LRPT images have been successfully received (by also checking the menu item below) then these will be saved to disk after image processing, if enabled.
• Decode Images: Checking this menu item starts the LRPT Decoder and if the Costas PLL is locked, LRPT images will be decoded and progressively displayed in the image display frame.
• Save Images: Activating this menu item will cause glrpt to save the channel images during reception, without any image processing and as they were received from the satellite. This action is not available once receiving and decoding of images has been terminated.
• Operation timer: Opens a pop-up dialog for setting the Duration (in minutes) of the Decoding operation. The default duration can be set up in the ~/glrpt/glrptrc configuration file.
• Start-Stop timer: Opens a pop-up dialog for setting the Start and Stop times (in hrs and min) of the Receiving, Demodulating and Decoding process. At the end of the timed operation, any images successfully decoded will be saved on the disk.
• Cancel timer: Cancels the above timer. This leaves the Operation timer set to the difference between the stop time and start time above.
• Satellite type: Select the Satellite to work with. Currently Meteor-M1 and Meteor-M2 are listed but Meteor-M1 now seems defunct.
• Save Raw Images: Enables saving of Raw images as produced by the LRPT decoder.
• Enable Normalization: Enables Luminance histogram normalization of received images, e.g. will change pixel values so that luminance values range from black to white. This will also "stretch" the contrast if the image is "flat".
• Enable C.L.A.H.E.: Enables the "Contrast Limited Adaptive Histogram Equalization" algorithm by Karel Zuiderveld, which provides excellent regional enhancement of contrast but it has to follow my own simple Histogram Normalization function, so the menu item above must be enabled also.
• Rectify Images: Enables rectification (correction of tangential geometric distortion) of raw Meteor-M images.
• Invert Images: This will enable the inversion (flipping) of images received during South to North passes. These of course produce "upside-down" images.
• Combine Images: Enables the combining of three monochrome images into one pseudo-color image. This only works well if suitable APID's are transmitted by the satellite.
• Individual Images: Enables the saving of individual Greyscale images decoded from the satellite. This option should be on if the Red channel is replaced by an Infrared channel.
• Pseudo Colorize: Enables some speculative additional pseudo-colorization of the combination image. This is experimental and may be left unchecked by default.
• Save As JPEG: Enables the saving of the Greyscale channel (APID) images in the JPEG file format. The new built-in JPEG compressor can now handle the color image also.
• Save As PGM: Enables the saving of the Greyscale channel (APID) images in the PGM file format.
• Quit: Quit glrpt. If an operation is running, a quit confirmation dialog is shown.

7. Bugs and annoyances:
I have fixed whatever bugs I came across testing glrpt but there may be some hiding, waiting for the right conditions to appear. This is a first 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 glrpt has two such functions for the user to choose from!

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 glrpt was able to receive, demodulate and decode LRPT images successfully, I added a number of widgets to the GUI to display glrpt's status. These include numerical displays of some important parameters and graphical displays of the FFT Spectrum and QPSK Constellation. This is the first beta release of glrpt on my website.

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: Made some changes to the pop-up menu code so that when an action is pending (e.g. the SDR receiver is being initialized) the pop-up menu is blocked. This is needed to stop the user changing selections in the menu while the application is in an undefined state. Also made changes to the QPSK constellation display code to streamline its operation.

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: I have changed the GTK+3 user interface to include horizontal level gauges to graphically display some of the operating parameters of glrpt, as well as their numerical value in text entries next to the gauges. I have also fixed a buffer overrun bug in the Histogram Normalization function that was reported by Coverity Scan.

Version 0.9-beta: I made some changes to the colorization policy of the level gauges, to improve their color coding. Hopefully this colorization is more representative of the values that control the level gauges. I have also made some changes to the code that handles the timer functions of glrpt, so that the timer wake-up alarm can be canceled at any time, once set. Canceling the timer resets it to the default duration specified in ~/glrpt/glrptrc.

Version 1.0: I have added a "Save Images" menu item to the Pop-up Menu which, when activated, will cause glrpt to save channel images as received from the satellite, without any image processing. This action is only available while glrpt is actually receiving and decoding images and it is intended to save partially received images, if needed.

Version 1.1: I made some changes in the Costas PLL so that when unlocked, instead of the PLL frequency wondering around within its allowed range (+/-9kHz), it scans linearly from -9kHz to 9kHz and back, looking for a lock on the signal. This became necessary, because the PLL frequency sometimes would get stuck too far away in its range for a lock to be obtained on the satellite signal.

Since I have been using glrpt without any obvious bugs showing, and since I have no feedback from users, if any, I have made this a release, non-beta, version. Bug reports welcome!

Version 1.2: I fixed a bug that caused glrpt to crash with a segmentation fault when reception was restarted and stopped after first receiving and decoding images. Note! I was not able to test this bug fix because Meteor M2 seemed to have gone off the air at the time.

Version 1.3: I added code to the function that creates the combination pseudo-color image, to raise the minimum value of pixels in the blue APID channel to about hex40 (64), if normalization of the monochrome channel images is enabled. This is because the color of watery areas (sea and lakes etc) turns out very dark, since the blue channel image's pixel values of dark areas are "stretched" down to zero.

Version 1.4: Not happy with the above mods, I have added additional items in the ~/glrpt/glrptrc config file and modified the colorization functions so that colorization parameters can be specified by the user in the runtime config file.

Version 1.4.1: I changed the sequence of actions that open and initialize the RTL-SDR receiver because under some fault conditions, uninitialized strings were sent to the Messages text buffer causing GTK to print error messages in the console.

Version 1.5: I fixed some minor bugs reported by LLVM's clang-analyzer tool. Also I refined the pseudo-colorization code after a number of experiments with different colorization schemes. By popular request, I added a short Quick Start section in this manual.

Version 1.6: Added an new item in the ~/glrpt/glrptrc 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.7: Added a new item in the ~/glrpt/glrptrc configuration file, to specify whether to use Automatic or Manual Receiver Gain Control, and in the latter case to specify the required Gain. It was of course necessary to modify the GUI to include widgets for selecting Manual or Auto Gain Control and to adjust the Receiver Gain.

Version 1.8: By popular request I modified glrpt (extensively) to work with the SoapySDR library, which provides a generalized API for handling different SDR receivers. It should now be possible for glrpt to work with some of the more popular SDR devices, like RTL-SDR, Airspy R2 and Mini, Hack RF, Lime SDR etc. It is now no longer necessary to specify the SDR device name since glrpt will auto-detect any SDR device compatible with SoapySDR. The device index number (0 for the first detected device, 1 for the second etc) must be specified in the glrptrc config file and also a new configuration item, the Scale Factor to apply to the value of I/Q data streamed from the SDR receiver, via SoapySDR. Also the sampling rate of the SDR device and the effective sampling rate of the Demodulator need not be specified as they are set up automatically by glrpt. For now glrpt has been tested with RTL-SDR and Airspy R2 and Mini devices.

Version 1.8.1: I added a new configuration entry in glrptrc to specify an Image APID whose palette is to be inverted, e.g. pixel values in the range 0 - 255 to be mapped into a range of 255 - 0. This is more useful in the case of the infrared image were hot is normally white and cold black.

Version 1.9: I changed the I/Q data streaming and processing functions so that a no-copy double buffer system is used to convey data between them. I have also moved the low pass Chebyshev filter and FFT waterfall functions from SoapySDR's data streaming function to the main demodulator's body. Hopefully this will improve operation of glrpt on lower performance computers.
I have also added code to automatically scale incoming sample data so that it is no longer necessary to specify a scale factor for individual SDR receivers. This item has been removed from the glrptrc configuration file and the user interface now shows the ALC (Automatic Level Control) loop gain and the average sample data magnitude.

Version 2.0: I have added code to allow the user to specify, in the glrptrc configuration file, the names and frequencies of satellites of interest. These will be used to create the "Select Satellite" list in glrpt's pop-up menu. Optimistically, this will make it a lot easier to include new satellites to be launched in the future ;-).
I removed the auto sample data scaling introduced in version 1.9 since it appears that it affects the operation of the QPSK demodulator, somehow. I also made changes to the Costas PLL parameters to improve lock acquisition and stability and I disabled the up-down scanning of the PLL's center frequency when of-lock.
I have added an additional item in the pop-up menu to enable saving of Raw images, as they are produced by the LRPT decoder and before they are processed by the Normalization and CLAHE functions.

Version 2.1: By trial and error and testing, I edited the value of some parameters, mainly of the ALC and Costas PLL functions, to improve the sensitivity of glrpt to the satellite's signals. There is occasionally some intermittent failure of PLL lock at very low elevations, but this is compensated by earlier PLL lock and start of image decoding. I have also carried out some cleanup of the source code in some places.

Version 2.2: Added an extra line in the glrptrc configuration file to specify the glrpt Channel numbers to be used for the creation of the Combined pseudo-color image. Normally channels 0, 1, and 2 are used as sources for the red, green and blue channels of the colored image. When the actual Red sensor channel is replaced by the Infra-red channel, the combined color image is red-dominated and of poor quality. Under such conditions, Red channel number 0 can be replaced by another one, usually the Green channel number 1, and may give fair results in conjunction with suitable pixel value ranges specified in glrptrc.
Another change is a modification of the RRC filter code, to reduce processor workload and memory block moves. Demodulator workload is reduced by about 5-6%, which is not great but still desirable on slower platforms.

Version 2.2.1: Fixed a bug in the code that implements the "Save Images" pop-up menu item, which prevented saving when images where already processed by the Normalization and CLAHE functions.

Version 2.2.2: By user request, the acceptable receiver filter bandwidth can now be between 100kHz and 200kHz.

Version 2.3: Rich Griffiths W2RG has contributed code to rectify (correct tangential geometric distortion) of the raw Meteor-M2 images. His original application, rectify-jpg, can open JPEG images (monochrome or color combined) as produced by glrpt and then can rectify the geometric distortion and re-save images as jpeg's. The working parts of this code have been incorporated into glrpt, with some modifications, so now glrpt can natively produce rectified Meteor-M2 images.

Version 2.4-beta: With the successful launch of Meteor-M2-2, I have modified glrpt so that it can now configure itself by reading per-satellite configuration files. These are expected to be in glrpt's working directory (/home/<user-dir>/glrpt/) and also have a ".cfg" file extension. BUT PLEASE NOTE: Support for M2-2 signals is work in progress, especially in the 80k Interleaved Differential OQPSK mode. Please do not use this mode (seems to be the current mode) till difficulties are resolved. 72k DOQPSK may be usable.

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.

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 glrpt. Unfortunately artlav's image decoder code "medet" does not support OQPSK, so glrpt 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 glrpt 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 glrpt, provisionally, as version 2.4-beta, for testing.

Version 2.4.1-beta: 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 2.4.2-beta: Mostly code cleanup and removal of some code, used in debugging the new demodulator and decoder functions.

Version 2.4.2: Having failed to find a way to preserve the live images and QPSK constellation preview in glrpt, for the 80kS/s interleaved DOQPSK mode, I was forced to forgo the above and settle for a decoder that produces the previews, (and actual images) only when receiving has been ended by the user or the timer. Hopefully in the future some way may be found, but only if Meteor M2-2 resumes 80k mode transmissions.

Version 2.4.3: Fixed a bug that was causing Image Channel 2 (the Blue channel) luminance to be changed when saving manually, using the "Save Images" menu item. The change of luminance was brought about by the Colorization function when enhancing the colored combined image.

Version 2.4.4: Made some changes to the Costas PLL loop to improve phase lock capture and stability.

Version 2.4.5: Fixed some of the more important warnings produced by cppcheck and adopted some changes in the source code, provided by Viktor Drobot who is now developing a fork of glrpt on github.

Version 2.5: 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. This introduces a change in the configuration file since the interpolation factor is not needed. Please make sure you go through the configuration file and verify the settings.

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 2.5.1: As suggested by Peter DG4EK, I removed the G_SOURCE_FUNC casting macro from g_idle_add() near line 245 in the Glrpt/callback_func.c file, because in some distros this macro was not found by the compiler.

Version 2.5.2: After a bug report by Peter DG4EK, I replaced the atof() function with a function of my own to allow glrpt to read decimal numbers with both a '.' or ',' as a decimal point.

Version 2.5.3: I replaced the double buffer system of transferring data from the SDR receiver to the demodulator with a circular (ring) buffer system. This was needed to allow the data sourcing and data consuming threads to run asynchronously, without loss of data, when the computer is under heavy workload.

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.

Version 2.5.4: Made several changes to the structure of the program to better interface with the GTK+ toolkit, to avoid an occasional lock-up of the Graphical User Interface.

Version 2.5.5: Made a change in the Display_Scaled_Image() function in Glrpt/image.c to silence an Undefined Behavior error message from the run time sanitizer.

Version 2.5.5: Fixed a bug in the pseudo-colorization code that prevented it from speculatively correcting the color of large water bodies, like the sea or large lakes.