DOC: Add quickstart for viewer to User Guide

doc/source/user_guide.txt

@@ -8,3 +8,4 @@ User Guide
    user_guide/plugins
    user_guide/tutorials
    user_guide/getting_help
+   user_guide/viewer

doc/source/user_guide/viewer.txt

@@ -0,0 +1,87 @@
+Image Viewer
+============
+
+
+Quick Start
+-----------
+
+
+``skimage.viewer`` provides a matplotlib_-based canvas for displaying images and
+a Qt-based GUI-toolkit, with the goal of making it easy to create interactive
+image editors. You can simply use it to display an image::
+
+   >>> from skimage import data
+   >>> from skimage.viewer import ImageViewer
+
+   >>> image = data.camera()
+   >>> view = ImageViewer(image)
+   >>> view.show()
+
+Of course, you could just as easily use ``imshow`` from matplotlib_ (or
+alternatively, ``skimage.io.imshow`` which adds support for multiple
+io-plugins) to display images. The advantage of ``ImageViewer`` is that you can
+easily add plugins for manipulating images. Currently, only a few plugins are
+implemented, but it is easy to write your own. Before going into the details,
+let's see an example of how a plugin is added to the viewer::
+
+   >>> import skimage
+   >>> from skimage.viewer.plugins import Canny
+
+   >>> image = skimage.img_as_float(data.camera())
+   >>> viewer = ImageViewer(image)
+   >>> viewer += Canny(view)
+   >>> viewer.show()
+
+At the moment, there aren't very many plugins pre-defined, but there's a really
+simple interface for creating your own plugin. First, let's create a plugin to
+call the total-variation denoising function, ``tv_denoise``:
+
+.. code-block:: python
+
+   from skimage.filter import tv_denoise
+   from skimage.viewer.plugins.base import Plugin
+
+   denoise_plugin = Plugin(image_filter=tv_denoise)
+
+.. note::
+
+   The ``Plugin`` assumes the first argument given to the image filter is the
+   image from the image viewer. In the future, this should be changed so you
+   can pass the image to a different argument of the filter function.
+
+To actually interact with the filter, you have to add widgets that adjust the
+parameters of the function. Typically, that means adding a slider widget and
+connecting it to the filter parameter and the minimum and maximum values of the
+slider:
+
+.. code-block:: python
+
+   from skimage.viewer.widgets import Slider
+   from skimage.viewer.widgets.history import SaveButtons
+
+   denoise_plugin += Slider('weight', 0.01, 0.5, update_on='release')
+   denoise_plugin += SaveButtons()
+
+Here, we connect a slider widget to the filter's 'weight' argument.  We also
+added some buttons for saving the image to file or to the ``scikits-image``
+image stack (see ``skimage.io.push`` and ``skimage.io.pop``).
+
+All that's left is to create an image viewer and add the plugin to that viewer.
+
+.. code-block:: python
+
+   from skimage import data
+   from skimage.viewer import ImageViewer
+
+   image = data.coins()
+   viewer = ImageViewer(image)
+   viewer += denoise_plugin
+   viewer.show()
+
+
+.. image:: data/denoise_viewer_window.png
+.. image:: data/denoise_plugin_window.png
+
+
+.. _matplotlib: http://matplotlib.sourceforge.net/
+