diff --git a/.gitignore b/.gitignore index a7c4171..804e118 100644 --- a/.gitignore +++ b/.gitignore @@ -43,7 +43,8 @@ # Program specifics *.png !textlogo.png -!palettes/* +!palettes/*.png +!util/*.png *.wav aptdec diff --git a/README.md b/README.md index c67526c..c035604 100644 --- a/README.md +++ b/README.md @@ -2,126 +2,97 @@ Copyright (c) 2004-2009 Thierry Leconte (F4DWV), Xerbo (xerbo@protonmail.com) 2019-2020 -## Description +## Introduction -Aptdec is an FOSS program that decodes images transmitted by NOAA weather satellites. These satellites transmit continuously (among other things), medium resolution (1px/4km) images of the earth on 137 MHz. -These transmissions could be easily received with an simple antenna and cheap SDR. Then the transmission can easily be decoded in narrow band FM mode. +Aptdec is a FOSS program that decodes images transmitted by NOAA weather satellites. These satellites transmit constantly (among other things) medium resolution (4km/px) images of the earth over a analog mode called APT. +These transmissions can easily be received with a cheap SDR and simple antenna. Then the transmission can be decoded in narrow FM mode. -Aptdec can convert these audio files into `png` images. +Aptdec can turn the audio recordings into PNG images and generate images such as: -For each audio file up to 6 images can be generated: + - Raw image: both channels with full telemetry included + - Individual channel: one of the channels form the image + - Temperature image: a temperature compensated image derived from the IR channel + - Palleted image: a image where the color is derived from a palette (false color, etc) + - MCIR: a false color that uses a underlay map for color -1. Raw image: contains the 2 transmitted channel images + telemetry and synchronization pulses. -2. Calibrated channel A image -3. Calibrated channel B image -4. Temperature compensated IR image -5. Palleted image -6. MCIR (Map Color InfraRed) image +The input audio format can be anything supported by `libsndfile` (although only tested with WAV and FLAC). Sample rate doesn't matter, although lower samples rates will process faster. -The input audio file must be mono with a sample rate in the range of 4160-62400 Hz, lower samples rates will process faster. -Aptdec uses `libsndfile` to read the input audio, so any format supported by `libsndfile` may be used (however it has only tested with `.wav` files). - -## Compilation - -Aptdec is portable since it is written in standard C. -It has successfully compiled and ran on Debian with both `gcc`, `clang` and `tcc` and will most likely work on any Unix platform. -Just edit the Makefile and run `make` (no configure script as of right now). - -Aptdec uses `libsndfile`, `libpng` and `libm`. -The `snd.h` and `png.h` headers must be present on your system. -If they are not on standard path, edit the include path in the Makefile. - -## Usage - -To compile -`make` - -To run without installing -`./aptdec [options] audio files...` - -To install -`sudo make install` - -To run once installed -`aptdec [options] audio files...` - -To uninstall -`sudo make uninstall` - -## Options +## Quick start +```sh +sudo apt install git gcc libsndfile-dev libpng-dev +git clone https://github.com/Xerbo/aptdec.git && cd aptdec +make ``` --i [r|a|b|t|m|p] -Output image type -Raw (r), Channel A (a), Channel B (b), Palleted (p), Temperature (t) or MCIR (m) -Default: "ab" - --d -Images destination directory (optional) -Default: Current directory - --s [15|16|17|18|19] -Satellite number -For temperature calibration -Default: "19" - --e [r|a|b|c|t|m] -Effects -Histogram equalise (h), Crop Telemetry (t), Denoise (d), Precipitation (p) or Linear equalise (l) -Defaults: off --m -Map file generated by wxmap - --o -Output image filename - --p -Path to palette +## Examples --r -Realtime decode. When decoding in realtime it is highly recommended to choose a plain raw image. +To create an image from `gqrx_20200527_115730_137914960.wav` (output filename will be `gqrx_20200527_115730_137914960-r.png`) +```sh +./aptdec gqrx_20200527_115730_137914960.wav ``` -## Output - -Generated images are outputted in PNG and are 24 bit RGB for all image types apart from pure greyscale images. +To manually set the output filename +```sh +./aptdec -o image.png gqrx_20200527_115730_137914960.wav +``` -Image names are `audiofile-x.png`, where `x` is: +Decode all WAV files in the current directory and put them in `images` +```sh +./aptdec -d images *.wav +``` - - `r` for raw images - - `a` channel A images - - `b` channel B images - - `p` for a paletted image - - `t` for temperature calibrated images - - `m` for MCIR images +Apply a denoise filter (see [Post-Processing Effects](#post-processing-effects) for a full list of post-processing effects) +```sh +./aptdec -e d gqrx_20200527_115730_137914960.wav +``` -Currently there are 6 available effects: +Create a temperature compensated image for NOAA 18 +```sh +./aptdec -i t -s 18 gqrx_20200527_115730_137914960.wav +``` - - `t` for crop telemetry, off by default, only has effects on raw images - - `h` for histogram equalise - - `d` for a median denoise filter - - `p` for a precipitation overlay - - `f` to flip the image (for southbound passes) - - `l` to linearly equalise the image, stretch the colors in the image to black and white +Apply a falsecolor palette +```sh +./aptdec -i p -p palettes/WXtoImg-N18-HVC.png gqrx_20200527_115730_137914960.wav +``` -## Examples +## Usage -`aptdec -d images -i ab *.wav` +### Arguments -This will process all `.wav` files in the current directory, generate calibrated channel A and B images and put them in the `images` directory. +``` +-i [r|a|b|t|m|p] Output type (kinda stackable) +-e [t|h|l|d|p|f] Effects (stackable) +-o Output filename +-d Destination directory +-s (15-19) Satellite number +-m Path to WXtoImg map +-p Path to palette +-r Realtime decode +``` -`aptdec -e dh -i b audio.wav` +### Image types -Decode `audio.wav` with denoise and histogram equalization and save it into the current directory. + - `r`: Raw Image + - `a`: Channel A + - `b`: Channel B + - `t`: Temperature + - `m`: MCIR (Map Color InfraRed) + - `p`: Palleted -`aptdec -e d -p palettes/N19-June-High-Vegetation.png -i p audio.wav` +### Post-Processing Effects -Create a false color image from the `N19-June-High-Vegetation.png` palette. + - `t`: Crop telemetry (only effects raw image) + - `h`: Histogram equalise + - `l`: Linear equalise + - `d`: Denoise + - `p`: Precipitation overlay + - `f`: Flip image (for southbound passes) ## Realtime decoding -As of recently a realtime output was added allowing realtime decoding of images. +Aptdec even supports decoding in realtime. The following decodes the audio coming from the audio device `pulseaudio alsa_output.pci-0000_00_1b.0.analog-stereo` ``` mkfifo /tmp/aptaudio @@ -129,17 +100,19 @@ aptdec /tmp/aptaudio sox -t pulseaudio alsa_output.pci-0000_00_1b.0.analog-stereo.monitor -c 1 -t wav /tmp/aptaudio ``` -Perform a realtime decode with the audio being played out of `alsa_output.pci-0000_00_1b.0.analog`. To stop the decode kill the `sox` process. +To stop the decode and calibrate the image simply kill the `sox` process. ## Palette formatting -Palettes are PNG images that are 256x256 in size with 24bit RGB color. The X axis is the value of Channel A and the Y axis is the value of Channel B +Palettes are just simple PNG images, 256x256px in size with 24bit RGB color. The X axis represents the value of Channel A and the Y axis the value of Channel B. + +## Further Reading -## Further reading +[User's Guide for Building and Operating +Environmental Satellite Receiving Stations](https://noaasis.noaa.gov/NOAASIS/pubs/Users_Guide-Building_Receive_Stations_March_2009.pdf) -[https://noaasis.noaa.gov/NOAASIS/pubs/Users_Guide-Building_Receive_Stations_March_2009.pdf](https://noaasis.noaa.gov/NOAASIS/pubs/Users_Guide-Building_Receive_Stations_March_2009.pdf) -[https://web.archive.org/web/20141220021557/https://www.ncdc.noaa.gov/oa/pod-guide/ncdc/docs/klm/tables.htm](https://web.archive.org/web/20141220021557/https://www.ncdc.noaa.gov/oa/pod-guide/ncdc/docs/klm/tables.htm) +[NOAA KLM coefficients](https://web.archive.org/web/20141220021557/https://www.ncdc.noaa.gov/oa/pod-guide/ncdc/docs/klm/tables.htm) ## License -See LICENSE. \ No newline at end of file +See `LICENSE` \ No newline at end of file diff --git a/main.c b/main.c index aac4042..1aaca5f 100644 --- a/main.c +++ b/main.c @@ -315,6 +315,13 @@ static void usage(void) { fprintf(stderr, "Aptdec [options] audio files ...\n" "Options:\n" + " -i [r|a|b|t|m|p] Output image\n" + " r: Raw\n" + " a: Channel A\n" + " b: Channel B\n" + " t: Temperature\n" + " m: MCIR\n" + " p: Paletted image\n" " -e [t|h|d|p|f|l] Effects\n" " t: Crop telemetry\n" " h: Histogram equalise\n" @@ -322,19 +329,12 @@ static void usage(void) { " p: Precipitation\n" " f: Flip image\n" " l: Linear equalise\n" - " -i [r|a|b|c|t|m|p] Output image\n" - " r: Raw\n" - " a: Channel A\n" - " b: Channel B\n" - " t: Temperature\n" - " m: MCIR\n" - " p: Paletted image\n" - " -d Image destination directory.\n" - " -o Output filename\n" + " -o Output filename\n" + " -d Image destination directory.\n" " -s [15-19] Satellite number\n" - " -m Map file\n" + " -m Map file\n" + " -p Path to palette\n" " -r Realtime decode\n" - " -p Path to palette\n" "\nRefer to the README for more infomation\n"); exit(EINVAL); diff --git a/palettes/N19-FC-June-High-Vegetation.png b/palettes/Falsecolor-N19-June-High-Veg.png similarity index 100% rename from palettes/N19-FC-June-High-Vegetation.png rename to palettes/Falsecolor-N19-June-High-Veg.png diff --git a/palettes/N19-June-High-Vegetation.png b/palettes/N19-June-High-Vegetation.png deleted file mode 100644 index 1d45d80..0000000 Binary files a/palettes/N19-June-High-Vegetation.png and /dev/null differ diff --git a/util/PrecipitationPalette.png b/util/PrecipitationPalette.png new file mode 100644 index 0000000..2ac2db0 Binary files /dev/null and b/util/PrecipitationPalette.png differ diff --git a/util/TempPalette.png b/util/TempPalette.png new file mode 100644 index 0000000..974c07d Binary files /dev/null and b/util/TempPalette.png differ diff --git a/util/Temperature.png b/util/Temperature.png new file mode 100644 index 0000000..012f57f Binary files /dev/null and b/util/Temperature.png differ