1. Introduction
xwxapt is the interactive X/GTK+ GUI version of the command-line
APT weather satellite decoding tool, wxapt. Currently xwxapt 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
and displayed 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 xwxapt.
Usage: xwxapt [-hv]
-h: Print this usage information and exit.
-v: Print version number and exit.
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. xwxapt inherits the same
image decoding engine and basic features of wxapt. 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.
xwxapt 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 xwxapt window are half the size of the ones that are written to the disk, so they are displayed at a rate of one line per second.
Sound-card set-up
xwxapt 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 xwxapt's 'samples' buffer
make the settings inaccurate. Audio level setting is now done manually
as a one-off procedure after installation of 'xwxapt', using the audio
level set-up function.
Synchronous decoding
xwxapt decodes images or records the APT signal in a synchronized
manner. Whether decoding images in real time or recording the APT
signal, xwxapt 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 xwxapt to abort if the sync train signature was not identified.
Normalization of images
xwxapt 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 un-checking the 'Normalize images' item in the pop-up menu.
Rotation of images
xwxapt can perform 180 degree rotation of the APT images if the 'Invert
images' item in the pop-up menu is checked. This is useful for righting
the inverted images produced by the North-to-South passes of the
satellites.
Modes of operation
xwxapt 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 pre-recorded samples of APT signals.
In either case, xwxapt 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. When decoding in real time, half-size
images are displayed progressively in the xwxapt main window as they form.
3. Compilation
Before compiling xwxapt, it may be necessary to customize some entries
in the header file xwxapt.h. There are seven 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,
the recording level device and the default duration of real-time operations.
'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", "igain" and 540 sec (9 min). 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.
Because I use 'GLADE' to build the GTK+ GUI and the package itself, compilation requires a different process: Run ./autogen.sh in xwxapt's top source directory to configure and create the Makefiles. Then run 'make' to produce the executable binary 'src/xwxapt'. This can then be copied to a suitable location, usually /usr/local/bin or /usr/bin. You can also run 'make install' to install the 'xwxapt' binary into /usr/local/bin. Use 'make distclean' before re-compiling the package. You might also want to run 'strip xwxapt' on the installed xwxapt binary to remove debugging symbols. There is only this hypertext documentation file which you can copy to a location of your choice.
4. Command line options
xwxapt's own command line options are:
-h: Print this usage information and exit.
-v: Print version number and exit.
xwxapt will also accept all the standard command line options that GTK+ itself can process with the gtk_init() initialization function.
5. Operation
The GTK+ user interface:
xwxapt's Main window contains the following widgets:
1. An image viewer that displays decoded APT images at half the
size of those saved to files on disk. When in real-time decoding, images
are shown progressively at the rate of one line per second. Each pixel
in the image viewer is the average of four pixels from the actual decoded
image so each line in the main window is made from two lines of the APT
image. Clicking on the image viewer toggles real-time APT decoding ON-OFF
and stops all other operations.
2. An Audio Level Indicator slider which shows the deviation from the required audio input level. Clicking on this widget toggles the audio level set-up function of xwxapt ON-OFF. Also during real-time image decoding, it indicates the audio input level as above.
3. A sync detector status indicator. This shows the condition of the sync detector - Search, Lock, Unlock and Stop, as well as the peak output level from the coherent filter that detects the APT sync train. Normal values are 1800-2400 for NOAA and 1500-2200 for Meteor type satellites.
4. A text view widget that is used by xwxapt to output messages relating to all aspects of its operation. All error messages are shown in red, successful actions in green and other information in black fonts.
5. A pop-up menu: This appears after a right-click on the main
window and has the following items:
Satellite type: Select satellite type - NOAA or Meteor.
Operation timer: Opens a pop-up dialog for setting the duration
(in minutes) of real-time operations.
Start-Stop timer: Opens a pop-up dialog for setting the start and
stop times of real-time operations.
Cancel timer: Cancels the above timer. This will start any suspended
operation that is selected.
Set up audio level: Starts the audio level set-up function of xwxapt.
Decode from dsp: Selects real-time image decoding by processing
data from the sound card's dsp.
Record to file: Selects the recording of APT signals to a file on disk.
Decode from file: Selects the decoding of images from a pre-recorded
APT signal.
Normalize images: Carry out histogram normalization of decoded images.
Invert images: Rotate images by 180 degrees. This is needed to righten
images decoded from south to north passes.
Stop: Stop all current processes.
Setting up working directories:
Before xwxapt is used to receive images, it is important to understand
how the resulting image files are named and saved. In normal usage,
xwxapt 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 prepended with images/ for image or record/ for recorded
audio files so that they are saved in ./images/ or ./record/ respectively.
This means that for normal operation xwxapt must be started from within
a directory containing images/ and record/ as sub-directories. The best
way to do this is to create a directory like /var/tmp/xwxapt/ containing
images/ and record/ and a soft link to /usr/local/xwxapt. This can be
done with ln -s /usr/local/bin/xwxapt /var/tmp/xwxapt. Then it is only a
matter of starting xwxapt by (double) clicking on the link's icon and
allowing it to save files to its default locations.
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, 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 xwxapt 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 manually to the correct level as follows:
Run xwxapt and start the audio level set-up function by either clicking on the 'Audio Level Indicator' slider, or by selecting the 'Set up audio level' item from the pop-up menu. While a clear and strong signal is being received from a NOAA-type satellite, adjust the volume control of the receiver so that the Audio Level Indicator's slider is at the center 0 error position. Generally the slider will move a little either side of the correct position but this is not a problem. Stop the audio level set-up function by either clicking on the 'Audio Level Indicator' slider again, or selecting the Stop item from the pop-up menu. This adjustment should normally be needed only once, although from time to time it may become necessary to re-adjust the receiver's level.
Direct real-time decoding:
1. Select the required satellite type from 'Satellite type' item
in the pop-up menu (currently the choice is NOAA or Meteor).
Also set the 'Normalize images' and 'Invert images' menu items to the
required state. 'Normalize images' is checked by default so that images
will be enhanced by a linear histogram normalization process.
2. If required, set either the duration (in minutes) of the decoding operation with the 'Operation timer' menu item, or the start and stop times of decoding using the 'Start-Stop timer' menu item. Otherwise the default time-out (as set in xwxapt.h, normally 9 minutes) will apply to the operation.
3. Click on the blank image viewer in the main window or select the 'Decode from dsp' item from the pop-up menu. In the former case, xwxapt will use default image file names based on the current date and time and the satellite type, while in the latter a file selection dialog will open and a different file name may be specified. If the start-stop timer has been set, the decoding operation will be suspended till the start time.
4. When the decoding process is started, xwxapt will first synchronize the dsp buffer with the APT sync train and then start decoding the APT image(s) line by line. Half-sized image(s) are displayed in the main window progressively and every two APT lines, e.g. once per second. The decoding operation will either stop when it times out (as set up in step 2), or if needed it can be stopped by clicking on the main window or selecting the 'Stop' menu item. This will also cause xwxapt 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 only difference is that this
process can only be selected from the 'Record to file' item of the pop-up
menu. The recording is done in a raw binary format (8 bits/sample at a
sampling rate of 9600 s/sec) and without any compression of data so a
recorded file can be quite large (about 4.5 Mb for a typical satellite
pass). This facility is really only useful for debugging and testing.
Decoding from a recorded APT signal:
This is done by selecting the 'Decode from file' menu item and then
choosing the recorded APT file from the file selection dialog. Decoded
image file names will have the same base string of the recorded file
but with the appropriate satellite type and file extension appended.
They will also be displayed at half size in the main window. PLEASE
NOTE that only files recorded by xwxapt can be processed!
6. Bugs and annoyances
I have fixed whatever bugs I came across testing xwxapt but there may
be some hiding, waiting for the right conditions to appear. Otherwise
the main inadequacy of xwxapt is its use of integer arithmetic only,
which results in images with slightly 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 efficient application, image quality is quite good
at least as far as meteorological uses go.
The Messages text view port does not always show text written to it, apparently because reading data from the sound card blocks rendering of the widget. Also sometimes the color of text is not correct, e.g. text that should be red appears black. Hopefully this bug will be fixed once I understand just what causes it. In the mean time text can be made to appear by scrolling the text view port up-down.
The hardest job xwxapt 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 xwxapt continuous by 'dead reckoning' the sync train position so short-lived noise will not throw xwxapt out of sync permanently.
Reading data from the sound card's dsp is done by an idle callback function and when the GTK+ GUI is busy, for example if xwxapt's window is moved around for a few seconds, then some dsp data is lost resulting in a loss of sync and spoiled images. So try to avoid any operations on your computer that can stall the sound card driver.
There has been a report of xwxapt 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 xwxapt. 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-beta This is the first release of xwxapt and my first
attempt at writing a significant GTK+ application. Please report any
bugs and suggestions for future versions.
Version 0.2-beta Made some changes to the Start-Stop timer pop-up
to stop reformatting of user input since it was activated by the loss
of focus signal and so it tended to mess-up the data entry fields when
the mouse was moved out of the window.
Removed some of the messages that were printed in the Messages window
during sound-card set-up since they were not properly rendered anyway.
Version 0.3-beta Managed to patch-up the problem of eratic rendering
of the Messages text viewer so I re-instated most of the messages that
were removed in version 0.2!
Also corrected the #define of the version number string so that this is
now correclty shown.
Version 0.4-beta Changed the process of configuring the package for compilation so that Glade's 'autogen' script is used to produce correct symlinks to 'automake' and a suitable 'configure' script.
Version 0.5 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:54 EET 2003