Merge pull request #1004 from jni/viewer-examples

Viewer examples

doc/source/user_guide/viewer.txt

@@ -32,7 +32,18 @@ let's see an example of how a pre-defined plugin is added to the viewer:
 
    viewer = ImageViewer(image)
    viewer += LineProfile(viewer)
-   viewer.show()
+   overlay, data = viewer.show()[0]
+
+The viewer's ``show()`` method returns a list of tuples, one for each attached
+plugin. Each tuple contains two elements: an overlay of the same shape as the
+input image, and a data field (which may be ``None``). A plugin class documents
+its return value in its ``output`` method.
+
+In this example, only one plugin is attached, so the list returned by ``show``
+will have length 1. We extract the single tuple and bind its ``overlay`` and
+``data`` elements to individual variables. Here, ``overlay`` contains an image
+of the line drawn on the viewer, and ``data`` contains the 1-dimensional
+intensity profile along that line.
 
 At the moment, there are not many plugins pre-defined, but there is a really
 simple interface for creating your own plugin. First, let us create a plugin to
@@ -74,8 +85,10 @@ All that's left is to create an image viewer and add the plugin to that viewer.
 
    viewer = ImageViewer(image)
    viewer += denoise_plugin
-   viewer.show()
+   denoised = viewer.show()[0][0]
 
+Here, we access only the overlay returned by the plugin, which contains the
+filtered image for the last used setting of ``weight``.
 
 .. image:: data/denoise_viewer_window.png
 .. image:: data/denoise_plugin_window.png

skimage/viewer/plugins/base.py

@@ -63,9 +63,9 @@ class Plugin(QtGui.QDialog):
     >>> plugin += Slider('threshold', 0, 255)       # doctest: +SKIP
     >>>
     >>> image = data.coins()
-    >>> viewer = ImageViewer(image) # doctest: +SKIP
-    >>> viewer += plugin            # doctest: +SKIP
-    >>> viewer.show()               # doctest: +SKIP
+    >>> viewer = ImageViewer(image)       # doctest: +SKIP
+    >>> viewer += plugin                  # doctest: +SKIP
+    >>> thresholded = viewer.show()[0][0] # doctest: +SKIP
 
     The plugin will automatically delegate parameters to `image_filter` based
     on its parameter type, i.e., `ptype` (widgets for required arguments must

viewer_examples/plugins/canny.py

@@ -6,4 +6,4 @@ from skimage.viewer.plugins.canny import CannyPlugin
 image = data.camera()
 viewer = ImageViewer(image)
 viewer += CannyPlugin()
-viewer.show()
+canny_edges = viewer.show()[0][0]

viewer_examples/plugins/canny_simple.py

@@ -21,4 +21,4 @@ plugin += SaveButtons(name='Save overlay to:')
 # Finally, attach the plugin to an image viewer.
 viewer = ImageViewer(image)
 viewer += plugin
-viewer.show()
+canny_edges = viewer.show()[0][0]

viewer_examples/plugins/lineprofile.py

@@ -6,4 +6,4 @@ from skimage.viewer.plugins.lineprofile import LineProfile
 image = data.camera()
 viewer = ImageViewer(image)
 viewer += LineProfile()
-viewer.show()
+line, profile = viewer.show()[0]

viewer_examples/plugins/lineprofile_rgb.py

@@ -6,4 +6,4 @@ from skimage.viewer.plugins.lineprofile import LineProfile
 image = data.chelsea()
 viewer = ImageViewer(image)
 viewer += LineProfile()
-viewer.show()
+line, rgb_profiles = viewer.show()[0]