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.
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.
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.
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.
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.
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
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.
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.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)
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