From 6b22ae32b577bc0f1eaf544ae6af0361ebdc39ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20Veres-Szentkir=C3=A1lyi?= <vsza@vsza.hu>
Date: Mon, 17 Jun 2013 13:23:56 +0200
Subject: [PATCH] added README

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cb85581
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+SSTV generator in pure Python
+=============================
+
+PySSTV generates SSTV modulated WAV files from any image that PIL can open
+(PNG, JPEG, GIF, and many others). These WAV files then can be played by any
+audio player connected to a shortwave radio for example.
+
+My main motivation was to understand the internals of SSTV in practice, so
+performance is far from optimal. I tried keeping the code readable, and only
+performed such optimizations that wouldn't have complicated the codebase.
+
+Command line usage
+------------------
+
+    usage: run.py [-h]
+                  [--mode {MartinM2,MartinM1,Robot24BW,ScottieS2,ScottieS1,Robot8BW}]
+                  [--rate RATE] [--bits BITS]
+                  image.png output.wav
+
+    Converts an image to an SSTV modulated WAV file.
+
+    positional arguments:
+      image.png             input image file name
+      output.wav            output WAV file name
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --mode {MartinM2,MartinM1,Robot24BW,ScottieS2,ScottieS1,Robot8BW}
+                            image mode (default: Martin M1)
+      --rate RATE           sampling rate (default: 48000)
+      --bits BITS           bits per sample (default: 16)
+
+Python interface
+----------------
+
+The `SSTV` class in the `sstv` module implements basic SSTV-related
+functionality, and the classes of other modules such as `grayscale` and
+`color` extend this. Most instances implement the following methods:
+
+ - `__init__` takes a PIL image, the samples per second, and the bits per
+   sample as a parameter, but doesn't perform any hard calculations
+ - `gen_freq_bits` generates tuples that describe a sine wave segment with
+   frequency in Hz and duration in ms
+ - `gen_values` generates samples between -1 and +1, performing sampling
+   according to the samples per second value given during construction
+ - `gen_samples` generates discrete samples, performing quantization
+   according to the bits per sample value given during construction
+ - `write_wav` writes the whole image to a Microsoft WAV file
+
+The above methods all build upon those above them, for example `write_wav`
+calls `gen_samples`, while latter calls `gen_values`, so typically, only
+the first and the last, maybe the last two should be called directly, the
+others are just listed here for the sake of completeness and to make the
+flow easier to understand.
+
+License
+-------
+
+The whole project is available under MIT license.
+
+Useful links
+------------
+
+ - receive-only "counterpart": https://github.com/windytan/slowrx
+ - free SSTV handbook: http://www.sstv-handbook.com/
+
+Dependencies
+------------
+
+ - Python 2.7 (tested on 2.7.5)
+ - Python Imaging Library (Debian/Ubuntu package: `python-imaging`)