Rewrite README, include util's, remove duplicate palette

.gitignore

@@ -43,7 +43,8 @@
 # Program specifics
 *.png
 !textlogo.png
-!palettes/*
+!palettes/*.png
+!util/*.png
 *.wav
 aptdec
 

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 <dir>
-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 <file>
-Map file generated by wxmap
-
--o <filename>
-Output image filename
-
--p <filename>
-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 <path>        Output filename
+-d <path>        Destination directory
+-s (15-19)       Satellite number
+-m <path>        Path to WXtoImg map
+-p <path>        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.
+See `LICENSE`

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 <dir>         Image destination directory.\n"
-	" -o <name>        Output filename\n"
+    " -o <path>        Output filename\n"
+	" -d <path>        Image destination directory.\n"
 	" -s [15-19]       Satellite number\n"
-	" -m <file>        Map file\n"
+	" -m <path>        Map file\n"
+    " -p <path>        Path to palette\n"
 	" -r               Realtime decode\n"
-	" -p               Path to palette\n"
 	"\nRefer to the README for more infomation\n");
 
 	exit(EINVAL);