1.
Introduction
wxapt is a non-interactive command line tool for decoding weather
images transmitted by satellites using the APT format. Currently
wxapt can decode images in the American NOAA and Russian Meteor
satellite APT formats. Images are decoded either in real time,
direct from the receiver's o/p and through the computer's sound
card, or from a file of sound samples recorded by wxapt.
Usage:
wxapt [-a<satellite>] [-s<start-time>[-<stop-time>] [-t<time>]
[-i<file>] [-p<file>] [-r[<file>]] [-R[<file>]] [-lnohv]
-a<satellite>: Satellite type: 0=NOAA 1=METEOR. Default is
NOAA. -s<start-time>: Time (UTC) in format hh:mm at which to
start APT recording or processing.
<stop-time>: Time (UTC) in format hh:mm at which to stop APT
recording or processing.
-t<duration>: Duration of APT recording or processing. If duration is greater than or equal to 60, it is taken as sec, else it is taken as min.
-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 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: Print a graph of audio input level error for setting up the receiver audio o/p level control. -n: Suppress histogram normalization of images which is performed by default.
-o: Rotate images by 180 degrees. Need to rectify inverted images produced by North-to-South satellites passes.
-h: Print this usage information and exit.
-v: Print version number and exit.
2. Features
wxapt was designed from the beginning to be simple and efficient,
decoding images using only integer arithmetic and simple processing
methods. The 2.4 kHz APT sub-carrier is sampled at 9.6 kHz, which
results in 4 samples per cycle of the sub-carrier, phased at 90
deg. The instantaneous amplitude A of the carrier is then
A=sqrt(x^2+y^2) where x and y are two consecutive samples at 90
deg. To comply with the design goal of using only integer
arithmetic, the sqrt is calculated using first the Taylor series
expansion in (x+y) e.g. A=(x+y)*sqrt( 1-2*x*y/(x+y) ) so the
first-order approximation is A=(x+y)*(1-x*y/(x+y). To reduce errors
due to integer arithmetic, this is calculated as
A=((x+y)*(x+y)-x*y)/(x+y).
Originally this first approximation was used alone but produced artifacts, in the form of slow modulation of the gray level of pixels with the difference between the sub-carrier frequency and sampling rate. With my sound card this was ~140 ppm and horizontal banding was evident in the decoded images.
After testing various approaches to improving the sqrt approximation, the simplest and most effective was to use one iteration of the Newton-Raphson method: A=(A*A+(x+y)*(x+y)-2*x*y)/A/2. Although this approach looks cumbersome and complex, it is quite accurate and much faster than floating point sqrt calculations. It also substantially reduced the problem of poor quality in decoded images.
Sound-card
set-up
wxapt automatically sets up the required sound card parameters
(sample format, sampling speed, mixer levels etc) for correct
operation. The Recording level set up is no longer automatic in
this version, because limitations in the resolution of mixer level
settings and incompatibility between the 'chunk' size of the dsp
buffer 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 -l option.
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 causes wxapt to abort if the sync train signature is 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 with the -n option.
Rotation of images
wxapt can perform 180 degree rotation of the APT images if the -o
option is specified. This is useful for righting the inverted
images produced by the North-to-South 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 the receiver and via the sound
card, or decoding images from a file of recorded samples of the APT
signal. 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,
grey scale wedges, margins etc) are removed form the images. APT
signal recording is done in straight binary format.
3.
Compilation
Before compiling wxapt, it may be necessary to customize some
entries in the header file wxapt.h. There are six items that may
need editing:
The ALSA sound card name (default is "hw:0").
The capture source (default is "Line").
The volume device (default is "Input").
The Stereo/Mono mode (number of channels, default is 2).
The capture volume level (default is 90 %).
The channel in use (default is RIGHT).
Stereo mode 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. It may help to use a
mixer application in order to find out the right names and settings
to use above.
Please note that I use Arch 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+ 2 and Glade-2, 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 "make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the xwxapt working directorey 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.
4. Command line
options
wxapt is a non-interactive command-line tool and can be invoked
with a number of option combinations, depending on the mode of
operation: For direct real-time image decoding, the
-a<satellite>, -s<time>, -t<duration> and
-i<file> options may be specified:
-a<satellite> specifies the satellite type transmitting the APT image: 0 = NOAA and 1 = METEOR. Default when -a is not used is to decode NOAA-type APT transmissions.
-s<start-time>[-<stop-time>] specifies the time (UTC) at which the recording or decoding process should start and optionally to stop. The format is hh:mm and if the specified time is behind actual real time, it will refer to the following day. If no stop-time is specified, the -t option can be used to specify the duration of recording or decoding. -t<duration> will override the stop time if specified.
-t<duration> specifies the duration of the recording or decoding process. If time is less than 60, it is taken as minutes, if 60 and above as seconds. This effectively specifies the height of the image in time*2 lines, since there are two lines/sec in the APT format. If -t is not used, wxapt will run until stopped by a user interrupt (Ctrl-C).
-i<file> specifies the prefix for the name of the image file(s) to be produced. The satellite type name will be appended to the prefix, e.g. wxapt -ifoo, reading APT signals from a NOAA satellite, will produce foo-NOAA_A.pgm and foo-NOAA_B.pgm image files for each channel. For Meteor satellites, foo-Meteor.pgm will be produced. Note that <file> can specify a file path, e.g. -i/var/tmp/Meteor/monday will result in monday-Meteor.pgm in /var/tmp/Meteor. If -i is not used, the date and time will be used as a file name prefix in the format ddMonyyyy-hhmmss.
When only recording an APT signal to a file, -s<time>, -t<time> and -r[<file>] can be used to specify the duration of the recording and the file name prefix for the samples file. If -t is not used, wxapt will run until interrupted by Ctrl-C and if <file> is not specified to -r, the time and date will be used instead. In both cases, the satellite type name and .bin will be appended to the prefix, e.g. for NOAA signals -ifoo will result in a recorded samples file named foo-NOAA.bin.
If recording to a file followed by decoding of images is desired, the -R[<file>] option can be used, optionally with -i<file> and -t<time>.wxapt will record the APT signal to a file and then decode image(s) from this file. If -R is used alone, wxapt will continue recording until stopped by a user interrupt. The date and time will be used as the samples file name prefix with the satellite name appended as for the -r option. Image file names will also have date and time as the prefix. If <file> is specified to -R. it will be the prefix for both samples file and image file(s). If -i<file> is used, the image file(s) will have their own file name prefix. Of course -t<time> can also be used.
To process images from a pre-recorded (by wxapt) samples file, the -p<file> option is used, optionally with -i<file>. -p<file> specifies the file from which wxapt is to decode images. If -i<file> is used also, the name prefix of the resulting image file can be specified, else the samples file name will be used, appended with the satellite name and .pgm.
-l starts wxapt in the sound level setting mode. A text bar-graph display indicates the error in the level of audio input from the receiver. The receiver's volume control should be adjusted so that the error is zero or as near as possible, e.g. the moving 'x' should stabilize in the center of the bar-graph: +->--x--<-+ . This adjustment need only be done once when the APT receiving system is ready and with a good, clear signal from a NOAA-type satellite. Meteor satellites have a slightly deeper sub-carrier modulation, so the audio o/p from the receiver is a little higher. Ctrl-C (user interrupt) is used to stop wxapt when adjustments are complete.
-n suppresses histogram normalization of the images.
-o rights inverted images produced by North-to-South passes of the
satellites.
Generally, wxapt will most likely be used only with the -t<time> for real-time decoding and with -r -t<time> for recording sound samples. The resulting files will have date and time as the file name, with the satellite type and file extension appended. Also the -o option will be needed to 'straighten' inverted images produced by the North-to-South passes of the satellites, while the no-histogram-normalization option -n will only be needed if image processing will be done in some other application.
5. Operation
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, grey-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, 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 by starting wxapt with the -l option. A text bar-graph display will indicate the error in the level of audio input from the receiver. The receiver's volume control should be adjusted so that the error is zero or as near as possible, e.g. the moving 'x' should stabilize in the center of the bar-graph: +->--x--<-+ . This adjustment need only be done once when the APT receiving system is ready and with a good, clear signal from a NOAA-type satellite. Meteor satellites have a slightly deeper sub-carrier modulation, so the audio o/p from the receiver is a little higher. Ctrl-C (user interrupt) is used to stop wxapt when adjustments are complete.
With the receiver connected as above and receiving an APT signal, start wxapt with no options or the -a option to specify satellite type. wxapt will set up the sound card and then arrange for the sync train to be at the beginning of the line buffer used for reading samples from the dsp. This is done by dummy-reading the samples ahead of the sync train, until this is near the beginning of the buffer.
Once buffer reading is synchronized, wxapt will start either decoding image(s) directly or recording the APT signal to a file, according to command line options. If the -t or -s option is used, wxapt will stop when timed out, otherwise it must be stopped by user interrupt (Ctrl-C). Image or sample files are written in the current directory unless a file path is specified with the -r, -R and -i switches.
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.
Otherwise the main inadequacy of wxapt is its use of integer
arithmetic only, which results in images with somewhat lower
quality compared to ones processed in floating point. Also for the
same reason, there is a little geometric distortion since an
integer number of carrier samples must be summated in each pixel (3
for NOAA images and 5 for Meteor). But for a simple and limited
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 continuous by 'dead reckoning' the sync train position so short-lived noise will not throw wxapt out of sync permanently.
There have been reports of wxapt exiting with error messages about sound-card set-up failures which are due to ioctl() calls failing. This appears to be due to the sound card driver not being compatible with the OSS API that is used in wxapt. I presume this can only be fixed by using a sound card that has an OSS-compatible driver. Unfortunately I did not have this problem on my computer so I cannot really investigate.
7. Version historyVersion 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.
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.
Last modified: Sat Mar 8 07:15:27 EET 2003