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 only. Other formats may be supported in
future versions if I can receive signals from the relevant
satellites and find enough information on the format used as well.
Images are decoded either in real time direct from the receiver o/p
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 mixer and dsp device names, the Stereo/Mono mode, the Left/Right
channel selection if stereo mode is selected, the recording source name
and the recording level device. 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.
The defaults are "/dev/mixer", "/dev/dsp", 2 (Stereo), LEFT, "line" and "igain". The dsp and mixer device names are likely to be correct for most systems, but stereo/mono mode, sound input device and recording level device names may need to be changed for different systems. The sound input devices are usually "line", "line1" ... or "mic" and the recording level device is "igain" or "rec". These names are listed in the soundcard.h file, usually in /usr/include/linux, but starting a mixer control application should show which devices are available in the system.
Compilation is very simple, just run 'make' in the wxapt source
directory to produce the executable binary 'wxapt'. This can then
be copied to a suitable location, usually /usr/local/bin or /usr/bin.
You can also type 'make install' to install the 'wxapt' binary into
/usr/local/bin and this hypertext documentation in /usr/local/doc.
Type 'make uninstall' to remove the 'wxapt' binary and the 'wxapt.html'
documentation file.
Type 'make clean' to remove all files produced by compilation except for
the 'wxapt' binary, from the source directory.
Type 'make distclean' to remove all but the files that were included in
the original source directory.
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 history
Version 0.1 was a simple unsynchronized 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.
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:
8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.
Last modified: Sat Mar 8 07:49:28 EET 2003