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 ``scikit-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/