fill out a few cookbook recipies

docs/Makefile

@@ -217,3 +217,7 @@ pseudoxml:
 .PHONY: apidocs
 apidocs:
 	sphinx-apidoc -f -e -T -M -o . ../rasterio ../rasterio/rio ../rasterio/five.py
+
+.PHONY: publish
+publish: html
+	aws s3 sync _build/html/ s3://mapbox/playground/perrygeo/rasterio-docs --delete --acl public-read

docs/cookbook.rst

@@ -60,6 +60,49 @@ Creating a least cost path
 Using a scipy filter to smooth a raster
 ---------------------------------------
 
+This recipie demonstrates the use of scipy's `signal processing filters <http://docs.scipy.org/doc/scipy/reference/signal.html#signal-processing-scipy-signal>`_ to manipulate multi-band raster imagery
+and save the results to a new GeoTIFF. Here we apply a median filter to smooth
+the image and remove small inclusions (at the expense of some sharpness and detail).
+
+.. literalinclude:: recipies/filter.py
+    :language: python
+    :linenos:
+
+.. code::
+
+    $ python docs/recipies/filter.py
+
+
+The original image
+
+.. image:: img/RGB.byte.jpg
+    :scale: 50 %
+
+With median filter applied
+
+.. image:: img/filtered.jpg
+    :scale: 50 %
+
 Using skimage to adjust the saturation of a RGB raster
 ------------------------------------------------------
 
+This recipie demonstrates the use of manipulating color with the scikit image `color module <http://scikit-image.org/docs/stable/api/skimage.color.html>`_.
+
+.. literalinclude:: recipies/saturation.py
+    :language: python
+    :linenos:
+
+.. code::
+
+    $ python docs/recipies/saturation.py
+
+
+The original image
+
+.. image:: img/RGB.byte.jpg
+    :scale: 50 %
+
+With increased saturation
+
+.. image:: img/saturation.jpg
+    :scale: 50 %

docs/recipies/filter.py

@@ -0,0 +1,16 @@
+import rasterio
+from scipy.signal import medfilt
+
+path = "tests/data/RGB.byte.tif"
+output = "/tmp/filtered.tif"
+
+with rasterio.open(path) as src:
+    array = src.read()
+    profile = src.profile
+
+# apply a 5x5 median filter to each band
+filtered = medfilt(array, (1, 5, 5)).astype('uint8')
+
+# Write to tif, using the same profile as the source
+with rasterio.open(output, 'w', **profile) as dst:
+    dst.write(filtered)

docs/recipies/saturation.py

@@ -0,0 +1,55 @@
+import rasterio
+import numpy as np
+from skimage.color import rgb2lab, lab2lch, lch2lab, lab2rgb
+
+path = "tests/data/RGB.byte.tif"
+output = "/tmp/saturation.tif"
+
+
+def saturation(arr, sat):
+    """Multiple saturation/chroma in LCH color space
+    Input and output are 3-band RGB scaled 0 to 255
+    """
+    # scale image 0 to 1
+    arr_norm = arr / 255.0
+    # Convert colorspace
+    lch = rgb2lch(arr_norm)
+    # Adjust chroma, band at index=1
+    lch[1] = lch[1] * sat
+    # Convert colorspace and rescale
+    return (lch2rgb(lch) * 255).astype('uint8')
+
+
+def rgb2lch(rgb):
+    """Convert RBG to LCH colorspace (via LAB)
+    Input and output are in (bands, cols, rows) order
+    """
+    # reshape for skimage (bands, cols, rows) -> (cols, rows, bands)
+    srgb = np.swapaxes(rgb, 0, 2)
+    # convert colorspace
+    lch = lab2lch(rgb2lab(srgb))
+    # return in (bands, cols, rows) order
+    return np.swapaxes(lch, 2, 0)
+
+
+def lch2rgb(lch):
+    """Convert LCH to RGB colorspace (via LAB)
+    Input and output are in (bands, cols, rows) order
+    """
+    # reshape for skimage (bands, cols, rows) -> (cols, rows, bands)
+    slch = np.swapaxes(lch, 0, 2)
+    # convert colorspace
+    rgb = lab2rgb(lch2lab(slch))
+    # return in (bands, cols, rows) order
+    return np.swapaxes(rgb, 2, 0)
+
+
+with rasterio.open(path) as src:
+    array = src.read()
+    profile = src.profile
+
+# Increase color saturation by 60%
+array_sat = saturation(array, 1.6)
+
+with rasterio.open(output, 'w', **profile) as dst:
+    dst.write(array_sat)