update documentation

Author: swharden

README.md

@@ -3,78 +3,91 @@
 
 ![](data/mozart.jpg)
 
-**Quickstart:** The code below converts a WAV file to a spectrograph and saves it as an image. This code analyzed [Mozart's Piano Sonata No. 11 in A major](https://www.youtube.com/watch?v=aeEmGvm7kDk) to produce the picture above.
+## Quickstart
+
+### Song to Spectrogram
+The code below converts a WAV file to a spectrograph and saves it as an image. This code analyzed [Mozart's Piano Sonata No. 11 in A major](https://www.youtube.com/watch?v=aeEmGvm7kDk) to produce the picture above.
 
 ```cs
-var spec = new Spectrogram.Spectrogram(fftSize: 2048);
-float[] values = Spectrogram.WavFile.Read("mozart.wav");
-spec.Add(values);
-spec.SaveImage("mozart.jpg");
+// load audio and process FFT
+var spec = new Spectrogram.Spectrogram(sampleRate: 8000, fftSize: 2048, step: 700);
+float[] values = Spectrogram.Tools.ReadWav("mozart.wav");
+spec.AddExtend(values);
+
+// convert FFT to an image and save it
+Bitmap bmp = spec.GetBitmap(intensity: 2, freqHigh: 2500);
+spec.SaveBitmap(bmp, "mozart.jpg");
 ```
 
-## Realtime Audio Monitor
+### Human Voice
+This code analyzes audio from HAL's famous quote, "I'm sorry Dave, I'm afraid I can't do that". The output is can be rendered using different colormaps.
 
-A demo program is included which monitors the sound card and continuously creates spectrograms from microphone input. It runs fast enough that the entire bitmap can be recreated on each render. This means brightness and color adjustments can be applied to the whole image, not just new parts.
+```cs
+// load audio and process FFT
+var spec = new Spectrogram.Spectrogram(sampleRate: 15000, fftSize: 4096, step: 400);
+float[] values = Spectrogram.Tools.ReadMp3("cant-do-that.mp3");
+spec.AddExtend(values);
+
+// convert FFT to an image and save it
+Bitmap bmp = spec.GetBitmap(intensity: .2, freqHigh: 1000,
+    colormap: Spectrogram.Colormap.grayscaleInverted);
+spec.SaveBitmap(bmp, "cant-do-that-grayscale-inverted.jpg");
+```
+colormap | sample output
+---|---
+**Grayscale Inverted** is used in many scientific publications when analyzing things like human voices and bird sounds|![](/data/cant-do-that-grayscale-inverted.jpg)
+**Grayscale** provides highest contrast output but does not benefit from color vision|![](/data/cant-do-that-grayscale.jpg)
+**Viridis** is the default colormap. It was specifically designed to represent 2D data in a way [ideally suited for human vision](https://www.youtube.com/watch?v=xAoljeRJ3lU).|![](/data/cant-do-that.jpg)
+**vdGreen** is the default colormap used for [QRSS-VD](https://github.com/swharden/QRSS-VD), a very old software project of mine. |![](/data/cant-do-that-green.jpg)
 
-![](data/screenshot4.gif)
+### QRSS Analysis
 
-This demo is available as a click-to-run EXE in [/dev/compiled-demos/](/dev/compiled-demos/)
+Experimenters with ultra-narrowband radio transmissions often use continuous wave  frequency-shifting radio transmitters to send data at very low rates over very long distances using very little power. See [_What is QRSS?_](https://www.qsl.net/m0ayf/What-is-QRSS.html) for more information. 
 
-## QRSS Spectrograph
+The following code produces a QRSS spectrogram from an MP3 file. This program took less than 5 seconds to analyze 30 minutes of audio, producing the image below.
 
-This library may be useful for displaying QRSS signals. I added some QRSS audio to the [/data](/data) folder to practice analyzing.
+```cs
+// load audio and process FFT
+var spec = new Spectrogram.Spectrogram(sampleRate: 8000, fftSize: 16384, step: 8000);
+float[] values = Spectrogram.Tools.ReadMp3("qrss-w4hbk.mp3");
+spec.AddExtend(values);
+
+// convert FFT to an image and save it
+Bitmap bmp = spec.GetBitmap(intensity: 1.5, freqLow: 1100, freqHigh: 1500,
+    showTicks: true, tickSpacingHz: 50, tickSpacingSec: 60);
+spec.SaveBitmap(bmp, "qrss.png");
+```
 
-![](data/qrss.jpg)
 
-The image above is from 10 minutes of audio processed by the program below. The entire program took less than 2 seconds to run.
+![](data/qrss.png)
 
-```cs
-var spec = new Spectrogram.Spectrogram(
-    fftSize: 8192, 
-    stepSize: 5000,
-    intensity: 2, 
-    pixelLower: 1250, 
-    pixelUpper: 1500
-    );
-    
-float[] values = Spectrogram.WavFile.Read("qrss.wav");
-spec.Add(values);
-spec.SaveImage("qrss.jpg");
-```
+## Demo Applications
+This project comes with a few interactive applications which serve as useful references for some of the ways this Spectrogram library can be used.
 
-#### New to QRSS?
-  * [What is QRSS?](https://www.qsl.net/m0ayf/What-is-QRSS.html)
-  * [QRSS and you](http://www.ka7oei.com/qrss1.html)
-  * [QRSS (slow CW)](https://sites.google.com/site/qrssinfo/QRSS-Slow-CW)
+### Download Demo EXE Files
+If you want to see what this library can do without downloading source code, click-to-run (EXE) demos are available in **[SpectrogramDemo.zip](/dev/compiled-demos/SpectrogramDemo.zip)**
 
-## Waterfall
-This demo program was created to demonstrate Spectrogram and ScottPlot working together.
+### Audio Monitor
 
-![](data/screenshot7.gif)
+A demo program is included which monitors the sound card and continuously creates spectrograms from microphone input. It runs fast enough that the entire bitmap can be recreated on each render. This means brightness and color adjustments can be applied to the whole image, not just new parts.
 
-## Developer Notes
+![](data/screenshot4.gif)
 
-![](/dev/graphics/theory-of-operation.png)
+### Waterfall with Graphs
+This demo program was created to demonstrate Spectrogram and ScottPlot working together.
 
-### TODO:
-* ~~render horizontally or vertically~~
-* ~~create bitmaps in real time from audio input~~
-* ~~advanced color (LUT) options~~
-* ~~advanced intensity options (nonlinear scaling)~~
-* create a user control to display a spectrogram
-* create a user control to adjust spectrogram settings
-* ~~options for bitmap to scroll or to statically repeat~~
-* create a way to convert between frequency and pixel position
-* optional display of axis labels (scales with ticks)
+![](data/screenshot7.gif)
+
+## Resources
 
 ### Similar Software
 * Argo ([website](http://digilander.libero.it/i2phd/argo/)) - closed-source QRSS viewer for Windows
 * SpectrumLab ([website](http://www.qsl.net/dl4yhf/spectra1.html)) - closed-source spectrum analyzer for Windows 
 * QrssPIG ([GitLab](https://gitlab.com/hb9fxx/qrsspig)) - open-source spectrograph for Raspberry Pi (C++)
-* Lopora ([website](http://www.qsl.net/pa2ohh/11lop.htm)) - open-source spectrograph (Python 3) 
+* Lopora ([GitHub](https://github.com/swharden/Lopora)) - open-source spectrograph (Python 3) 
 * QRSS VD ([GitHub](https://github.com/swharden/QRSS-VD)) - open source spectrograph (Python 2)
 
-### Spectrogram vs ~~Spectrograph~~
-* A spectrogram is an image
-* A spectrograph is a machine
-* Stop using the word spectrograph in software!
+### QRSS Information
+  * [What is QRSS?](https://www.qsl.net/m0ayf/What-is-QRSS.html)
+  * [QRSS and you](http://www.ka7oei.com/qrss1.html)
+  * [QRSS (slow CW)](https://sites.google.com/site/qrssinfo/QRSS-Slow-CW)