better readme, test files

README

@@ -14,20 +14,71 @@ rewrite it as an extension.
 Usage
 -----
 
+### API
+
 Seeklib.path_sig: takes a path to an image, and produces an imgseek fingerprint.
 
 Seeklib.calc_diff: takes two imgseek fingerprints and returns the difference score.
 
-Two caveats: 
+Allowed image types are any that CImg handles (IIRC jpg, gif, png,
+bmp, and maybe a couple others), or any that ImageMagick handles
+(basically all of them) if you have the ImageMagick library installed
+(CImg will call out to ImageMagick if it can't read an image itself).
+
+### Caveats:
 
 1. Note that the difference score is not as straightforward as the one
-generated by pHash. The score is a negative integer. The more
-negative, the more different the images are. It's not clear what the
-max difference score is. You should probably look here if you really
-need to know:
+   generated by pHash. The score is a negative integer. The more
+   negative, the more similar the images are. Personally, I find this
+   annoying to think about, so I'll add 50 to the result.
+
+2. The score resulting from comparing two identical images is
+   undefined. If this is possible in your application, consider
+   supplementing your comparison with good old-fashion sha1 or
+   something.
+
+3. It's not clear what the max difference score is. You should
+   probably look here if you really need to know, and read the
+   authors' original paper.
 
 http://grail.cs.washington.edu/projects/query/
 
-2. The score resulting from comparing two identical images is
-undefined. If this is possible in your application, consider
-supplementing your comparison with good old-fashion sha1 or something.
+### Example
+
+```ruby
+require 'seeklib'
+bss = SeekLib.path_sig 'squares/blue-square.jpg'    # what it sounds like
+gss = SeekLib.path_sig 'squares/green-square.jpg'   # pretty much same
+rss = SeekLib.path_sig 'squares/red-square.jpg'     # a bit different
+
+SeekLib.calc_diff(bss, gss) + 50           # => 18.641717640766657
+SeekLib.calc_diff(gss, bss) + 50           # => 18.641717640766657 (thank god)
+
+SeekLib.calc_diff(bss, rss) + 50           # => 46.336210565558794 (whoa!)
+SeekLib.calc_diff(gss, rss) + 50           # => 46.169410374857364 (similar)
+
+SeekLib.calc_diff(bss, bss) + 50           # => 17.969999238848686
+SeekLib.calc_diff(gss, gss) + 50           # => 17.969999238848686 (wait, diff(a, a) undefined?)
+SeekLib.calc_diff(rss, rss) + 50           # => 9.8899996727705 (yep, unfortunately)
+```
+
+Getting
+-------
+
+It's not actually published yet, so you have to do everything yourself.
+
+### Quick Way
+
+1. Get repo dradetsky/seeklib and build it.
+
+2. Place resulting libseek.so in this repo's `ext` directory.
+
+3. Substitute `require './lib/seeklib'` in the above script.
+
+### Long Way
+
+1. Get repo dradetsky/seeklib and build/install it. (ha ha! good luck!)
+
+2. `gem build seeklib.gemspec`
+
+3. `gem install seeklib-0.0.1.gem`