Merge pull request #301 from tonysyu/viewer-user-guide

DOC: Add Viewer Quickstart 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,85 @@
+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:
+
+.. code-block:: python
+
+   from skimage import data
+   from skimage.viewer import ImageViewer
+
+   image = data.coins()
+   viewer = ImageViewer(image)
+   viewer.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:
+
+.. code-block:: python
+
+   from skimage.viewer.plugins import Canny
+
+   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
+
+   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/
+

skimage/viewer/viewers/core.py

@@ -144,6 +144,8 @@ class ImageViewer(QMainWindow):
         self._img = image
         self._image_plot.set_array(image)
         clim = dtype_range[image.dtype.type]
+        if clim[0] < 0 and image.min() >= 0:
+            clim = (0, clim[1])
         self._image_plot.set_clim(clim)
         self.redraw()