1.
Introduction
wxapt is a non-interactive console application for the decoding of
APT weather satellite images. Currently wxapt can decode images
transmitted in the American NOAA and Russian Meteor satellite APT
formats. Images are decoded either in real time, direct from an
analogue receiver or a librtsdr-compatible dongle, or from a file
of sound samples recorded by wxapt. Starting from version 1.6-beta,
wxapt supports reception through the now very popular RTL-SDR
receiver dongles, available cheaply from many sources.
2. Features
The original wxapt application was designed from the beginning to
be simple and efficient, decoding images using only integer
arithmetic and simple processing methods. After version 0.8 the 2.4
kHz APT sub-carrier is sampled at 48 kHz instead of 9.6 kHz, since
software re-sampling in ALSA caused severe artifacts in the decoded
images. This also made it necessary to change the formula used to
calculate instantaneous carrier amplitude, since the phase angle
between consecutive samples is no longer 90 deg. To restore this
phase relationship, a ring buffer is used to store DSP samples over
1/4 period of the 2.4 kHz Sub-Carrier. For a 48kHz sampling rate,
this would require a ring buffer of 5 stages. The sub-carrier
amplitude is calculated by the hypotenuse of the current DSP sample
and one store at the end of the ring buffer.
Sound-card
set-up
If reception with a linear receiver is specified in wxaptrc config
file, wxapt automatically sets up the required sound card
parameters (sample format, sampling speed, mixer levels etc) for
correct operation. The Capture level set up is no longer automatic
in this version, because limitations in the resolution of mixer
level settings and incompatibility between the period size of the
PCM and wxapt's 'samples' buffer make the settings inaccurate.
Audio level setting is now done manually as a one-off procedure
after installation of 'wxapt', using the audio level set-up
function.
RTL-SDR Dongle
set-up
If reception with an RTL-SDR Dongle is specified in wxaptrc config
file, wxapt automatically sets up the required RTL-SDR parameters
(Center Frequency, Sampling Rate, Butterworth LPF cut-off etc) for
correct operation. The Signal Level setup is not required when
using the RTL-SDR dongle because this is set up permanently in the
source code and should be right with most compatible dongles.
Synchronous
decoding
wxapt decodes images or records the APT signal in a synchronized
manner. Whether decoding images in real time or recording the APT
signal, wxapt detects the sync train included in the APT format and
arranges for the samples buffer, used in reading from the dsp
device, to contain the sync train near its beginning. The result is
that image lines are aligned quite accurately and the recorded
samples are stored in a file in a line-by-line fashion. This makes
decoding from files easier and faster.
Detection of the sync pulse train is done by simulating a synchronous detector, matching the waveform of the sync pulse train. In NOAA type APT signals, the sync train of Channel A is detected and used for alignment of both images. In Meteor type APT signals there is only one image and sync train. The NOAA sync train is 7 cycles at 1040 Hz with a 1/1 mark/space ratio superimposed on the 2.4 kHz sub-carrier. The Meteor sync train is 5 cycles at 1200 Hz with a 2/1 mark/space ratio. Identification of satellite type and APT format is now not done automatically, since this process is unreliable in noisy signal conditions and caused wxapt to abort if the sync train signature was not identified.
Normalization of
images
wxapt performs simple (linear) histogram normalization of the APT
images to enhance low contrast, especially in the channel B images
of NOAA satellites. If normalization is not desired, it can be
suppressed by using the -n command-line option.
Pseudo-colorization of
images
wxapt can colorize the decoded gray scale images by using a simple
gray-level-to-color scheme, based on a color map in the
~/wxapt/wxaptrc file. This color map is specified by a table of
gray-scale range values with corresponding Red, Green and Blue
ranges. The table can have a maximum of six rows of gray-to-RGB
ranges which is enough for the simple scheme used by wxapt. More
details on the format of this color table scheme are in the
~/wxapt/wxaptrc file itself. Only the day-time A channel image of
the NOAA satellites is colorized, since the gray scale values of
other images don't represent ground features nearly enough.
Actually the NOAA colorized image is a hybrid of the day-time A and
B channel images, with ground features rendered from the A channel
and clouds from the B channel.
Rotation of images
wxapt can perform 180 degree rotation of the APT images if the -o
command line option is used. This is useful for righting the
inverted images produced by the South-to-North passes of the
satellites.
Modes of operation
wxapt has two modes of operation: Real-time decoding of APT images
directly from the audio output of a receiver via the sound card,
or from streaming ADC data from an RTL-SDR Dongle, or decoding
images from a file of pre-recorded samples of APT signals.
In either case, wxapt produces images in raw binary (P5 type) pgm
files, one for each of the two (ch A and ch B) images in NOAA APT
signals and one for the single Meteor APT image. In both cases the
various additions to the images (e.g. the sync train, gray scale
wedges, margins etc) are removed form the images. Pseudo-colorized
versions of the gray scale images are produced in raw binary (P6
type) ppm files. APT signal recording is done in straight binary
format.
3.
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 and there can also be sound card incompatibility
problems at run time.
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 "sudo make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the wxapt 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.
-a<satellite-type>: 0=NOAA-15 1=NOAA-18 2=NOAA-19 3=METEOR
-b:<LPF-cutoff>: Specify Low Pass Filter Cutoff in Hz
-c: Produce a pseudo-colorized image from NOAA A and B images
-f:<tuner-frequency>: Specify Tuner Center Frequency in Hz
-s<start-time[-<stop-time>]>: Time (UTC) in format hh:mm at which
to start and optionally to stop APT recording or processing
-t<duration>: Duration of APT recording or processing. If duration
is >= 60, it is taken as seconds, else as minutes
-i<file>: Specify image file name. If this option is not used,
use date and time as file name: ddMonyy-hhmm<extension>
-p<file>: Process images from samples recorded in <file>
-r[<file>]: Only record APT signal in <file>. If no file name is
specified, use date and time as file name: ddMonyy-hhmm.bin
-R[<file>]: Record APT signal in <file> and process images
If no file is specified, files will be named as above
-l: Start in audio input-level setup mode
-n: Suppress histogram normalization of images
-o: Rotate images by 180 degrees
-v: Print version number and exit
-h: Print this usage information and exit
5. Operation
Setting up working directories:
Before wxapt is used to receive images, it is important to
understand how the resulting image files are named and saved. In
normal usage, wxapt will be allowed to generate default file names
and store image and recorded APT files in its default directories.
The image and recorded audio 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 satellite type, image channel
(for NOAA) and the extension .pgm for images and .bin for recorded
audio are appended, to form the file name. This is then pre-pended
with images/ for image or record/ for recorded audio files so that
they are saved in <working-directory>/images/ or
<working-directory>/record/ respectively.
<working-directory> is "wxapt/" in the user's home
directory.
Before running wxapt, it may be necessary to customize some
entries in the wxapt/wxaptrc configuration text file in your home
directory. These are the items that will need editing:
The color-mapping tables may also need editing to get realistic colors (this is especially true for the green color) but this is not easy. Its best done by waiting for clear and dry weather, and then using an application like the Gimp to measure the gray scale values in various regions of the image. By comparing the image with a color map (like satellite images in Google Maps (tm)) the gray level ranges corresponding to water bodies, forested areas, land, desert etc can be identified and entered in the color tables in ~/wxapt/wxaptrc.
Stereo mode (e.g. specifying a "channel" name other than MONO) allows the computer's sound card to be connected to two audio sources, without the need to move plugs or switch audio. In my case this allows me to feed audio from my ham radio receiver and a weather satellite receiver to the sound card separately.
Audio level set-up: Weather satellites transmitting images in the APT format transmit in the 137 MHz band with medium-bandwidth (~40 kHz) FM modulation. The VHF carrier is modulated with a 2.4 kHz sub-carrier which in turn carries the image and related signals (sync train, Gray-scale wedge etc) as AM modulation. Considering the Doppler shift (~3 kHz) and possible errors in the receiver local oscillator(s) the recommended IF bandwidth for VHF APT reception is 50 kHz. Unfortunately few of the available popular receivers (scanners) have such a facility, so reception requires either a modification to the receiver or the use of wide-band FM modes. This results in a lot of interference (in my region at least) and more noise, resulting in poor image quality. However there are reasonably priced dedicated satellite receivers which can be used with excellent results (I use a Hamtronics R139).
Before wxapt is used to decode images or record samples with an analogue receiver, the sound card's recording source input, (usually "Line"), must be connected with the VHF receiver's o/p. The connection must be done with a suitable (normally 3.5 mm) stereo jack plug with either the left or right channel connected to the receiver's o/p if in stereo mode, or if in mono mode usually the left channel input should be used. Then the receiver's audio o/p level must be adjusted manually to the correct level as follows:
Run wxapt with the -l option and while a clear and strong signal
is being received from a NOAA-type satellite, adjust the
volume control of the receiver so that the print-out of the maximum
signal level is not more than suggested, e.g.
Signal Level: 31234 (Maximum 32000).
To receive images with an RTL-SDR Dongle, it is only necessary to plug the dongle into a USB2 port and connect the antenna to it. Software wise, it is necessary to install librtlsdr which is nowadays available in most Linux distros. This depends on libusb but this is also usually installed by default in most distros.
Direct real-time decoding:
1. Specify the required satellite type using the -a option,
e.g. wxapt -a>n< where n: 0 = NOAA-15, 1 = NOAA-18, 2 =
NOAA-19 and 3 = Meteor. If using an rtlsdr dongle, specify the
satellite's frequency using the -f option:
wxapt -a2
-f137100000 for NOAA-19.
2. Use the -c option to specify pseudo-colorization based on NOAA Ch.A and Ch.B images and the -o option to flip (rotate images 180) for South to North passages. Histogram normalization of image luminosity is on by default but it can be canceled using the -n option.
3. If required, set either the duration (in minutes) of
the decoding operation with the -t option, or the start and stop
times of decoding using the -s option so:
wxapt -a2 -f137100000 -c -o -t6 or wxapt -a2 -f137100000
-c -o -s12:40-12:46. Otherwise the default time-out of 10 min
will apply to the operation.
4. When the decoding process is started, wxapt will first synchronize the dsp buffer with the APT sync train and then start decoding the APT image(s) line by line. The decoding operation will either stop when it times out (as set up in step 3), or if needed it can be stopped by User Interrupt (Ctl+C). This will also cause wxapt to save image files to disk.
Recording APT signals to disk:
The process of recording APT signals to a file on disk is very
similar to direct decoding of images as above. The main difference
is that options affecting image processing have no effect. The
recording is done in a raw binary format (8 bits/sample at a
sampling rate of 48000 s/sec) and without any compression of data
so a recorded file can be quite large. This facility is really only
useful for debugging and testing:
wxapt -a2 -f137100000 -r -t6 will record samples from
NOAA-19 for 6 min into a file in ~/wxapt/record/ using a default
file name by date and time.
wxapt -a2 -f137100000 -R test-file -t6 will do as above but
after recording samples in "~/wxapt/record/test-file", wxapt will
also decode the images contained in the saved file.
Decoding from a recorded APT signal:
This is done by using the -p option with the pre-recorded file name
specified. Decoded image file names will have the same base string
of the recorded file but with the appropriate satellite type and
file extension appended. PLEASE NOTE that only files recorded by
wxapt can be processed!
6. Bugs and annoyances
I have fixed whatever bugs I came across testing wxapt but there
may be some hiding, waiting for the right conditions to appear.
There is a little geometric distortion since an integer number of
carrier samples must be summed in each pixel, but for a simple and
efficient application, image quality is quite good at least as far
as meteorological uses go.
The hardest job wxapt has to do is detecting the sync train included in APT transmissions. Although under good receiving conditions this seems to work very well, when there is some noise in the signal sync detection fails. However, under such conditions wxapt continues by 'dead reckoning' the sync train position so short-lived noise will not throw wxapt out of sync permanently.
7. Version history
Version 0.1 was a simple un-synchronized test bed for
learning about APT decoding and was not released.
Version 0.2 was a much better synchronized decoder and recorder but only for the NOAA type APT format and was not released.
Version 0.3-beta is the first beta release of wxapt incorporating code for the Meteor type APT format and many refinements in sync detection and file naming.
Version 0.4-beta incorporates linear histogram
normalization of the APT images produced, on by default but
suppressible with the -n option, and 180 degree rotation of the APT
images with the -o option.
A fix for an 'off-by-one' bug in a strcpy() statement, which could
affect the auto sound-card mixer level setup, is also
incorporated.
Version 0.5-beta incorporates an additional command line
option, -s<start-time>[-<stop-time>] which allows
automatic starting and/or stopping of wxapt at the time(s)
specified.
Processing of the -t<duration> option has been modified so
that if duration is >= 60, it is taken as seconds, else as
minutes.
Auto-detection of the recording level device has also been
incorporated to avoid incompatibilities between different
distributions regarding ioctl() request codes for setting recording
levels.
A bug in an ioctl() call for setting the recording level has been
fixed.
Version 0.6 beta has improved sync train detection reliability and stability and a fix for a bug that caused wxapt to abort with an error message after saving Meteor file images although there was no error.
Version 0.7 beta has an improved automatic recording/capture level setup process which takes into account the block size of the DSP which varies for different sound cards and drivers. This allows a useful increase of the pixel value range for an improved contrast.
Version 0.8 Added the ability to work in either stereo or mono mode so that more than one audio sources can be connected to the sound card without switching or removing plugs.
Version 0.9 Minor bug fixes and adjustment of image parameters to accommodate NOAA-17's apparently brighter images.
Version 1.0 After testing locally and receiving reports of successful operation by other users, this is the first release candidate version of wxapt. In this version automatic recording level setup and auto satellite-type recognition have been discarded mainly because of some unreliability in noisy signal conditions. Audio input level is set up once manually using the -l option and satellite type is specified with the -a command line option.
Version 1.1 In this version the margins of detection of
the Meteor type sync train have been widened to allow easier
synchronization of the dsp buffer with the APT signal.
The file format of the recorded APT signal has been changed so that
the 'satellite type number' is written as a 32 bit 'int' rather
than an 8 bit 'char' so that its much less likely for a non wxapt-
recorded file to be accepted for decoding.
The audio level set-up function has been modified slightly and as a
result the level indication when running 'wxapt -l' tends to wonder
up-down more than previously. This is not a problem if the audio
level adjustment is done so that successive indications are
centered around the '0' mark.
Version 1.2 Modified the sync train detection method so that the error in the dsp's sampling frequency is also measured. This error must be compensated to allow the sync detector to maintain lock during image decoding.
Version 1.3 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in wxapt source code and changed all "sprintf" commands to "snprintf" just in case. While going through the wxapt source code, I also fixed some minor bugs like typos and tidied error messages.
Version 1.4: Changed the source file tree to make it more like the correct arrangement commonly used nowadays. Change the sound card functions from the OSS API to the ALSA API as OSS is no longer fully supported.
Version 1.5: Made changes to the source code to silence many warnings that were issued by the LLVM clang compiler, when used with the -Weverything option. Changed the method of compilation to the established GNU Autotools way, by providing the various files needed (Makefile.am, configure.ac etc) to setup the build environment and to compile wxapt.
Version 1.6: Major changes introduced here, basically wxapt has been re-created from xwxapt by stripping out the Graphical User Interface and making the application non-interactive. A lot of things had to change, with the introduction of compatibility with librtlsdr dongles being the most important. Now wxapt is on par with xwxapt!
Version 1.7: I have fixed a bug in the calculation of phase changes in the FM Detector that demodulates the subcarrier.
Version 1.7.1: Correction! - the above fix apparently was not quite right so I changed the code again to compensate.
Version 1.7.2: Updated autogen.sh as well as configure.ac and Makefile.am
8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details