Merge pull request #705 from emmanuelle/userguide

Additions to the user guide: getting started section

doc/examples/plot_camera_numpy.py

@@ -0,0 +1,29 @@
+"""
+Using simple NumPy operations for manipulating images
+=====================================================
+
+This script illustrates how to use basic NumPy operations, such as slicing,
+masking and fancy indexing, in order to modify the pixel values of an image.
+"""
+
+import numpy as np
+from skimage import data
+import matplotlib.pyplot as plt
+
+camera = data.camera()
+camera[:10] = 0
+mask = camera < 87
+camera[mask] = 255
+inds_x = np.arange(len(camera))
+inds_y = (4 * inds_x) % len(camera)
+camera[inds_x, inds_y] = 0
+
+l_x, l_y = camera.shape[0], camera.shape[1]
+X, Y = np.ogrid[:l_x, :l_y]
+outer_disk_mask = (X - l_x / 2)**2 + (Y - l_y / 2)**2 > (l_x / 2)**2
+camera[outer_disk_mask] = 0
+
+plt.figure(figsize=(4, 4))
+plt.imshow(camera, cmap='gray', interpolation='nearest')
+plt.axis('off')
+plt.show()

doc/source/user_guide.txt

@@ -4,6 +4,8 @@ User Guide
 .. toctree::
    :maxdepth: 2
 
+   user_guide/getting_started
+   user_guide/numpy_images
    user_guide/data_types
    user_guide/plugins
    user_guide/tutorials

doc/source/user_guide/data_types.txt

@@ -1,3 +1,4 @@
+.. _data_types:
 
 ===================================
 Image data types and what they mean

doc/source/user_guide/getting_started.txt

@@ -0,0 +1,43 @@
+Getting started
+---------------
+
+``scikit-image`` is an image processing Python package that works with
+:mod:`numpy` arrays. The package is imported as ``skimage``: ::
+
+    >>> import skimage
+
+Most functions of ``skimage`` are found within submodules: ::
+
+    >>> from skimage import data
+    >>> camera = data.camera()
+
+A list of submodules and functions is found on the `API reference
+<http://scikit-image.org/docs/stable/api/api.html>`_ webpage.
+
+Within scikit-image, images are represented as NumPy arrays, for
+example 2-D arrays for grayscale 2-D images ::
+
+    >>> type(camera)
+    <type 'numpy.ndarray'>
+    >>> # An image with 512 rows and 512 columns
+    >>> camera.shape
+    (512, 512)
+
+The :mod:`skimage.data` submodule provides a set of functions returning
+example images, that can be used to get started quickly on using
+scikit-image's functions: ::
+
+    >>> coins = data.coins()
+    >>> from skimage import filters
+    >>> threshold_value = filters.threshold_otsu(coins)
+    >>> threshold_value
+    107
+
+Of course, it is also possible to load your own images as NumPy arrays
+from image files, using :func:`skimage.io.imread`: ::
+
+    >>> import os
+    >>> filename = os.path.join(skimage.data_dir, 'moon.png')
+    >>> from skimage import io
+    >>> moon = io.imread(filename)
+

doc/source/user_guide/numpy_images.txt

@@ -0,0 +1,82 @@
+A crash course on Numpy for images
+----------------------------------
+
+Images manipulated by ``scikit-image`` are simply NumPy arrays. Hence, a
+large fraction of operations on images will just consist in using NumPy::
+
+    >>> from skimage import data
+    >>> camera = data.camera()
+
+Retrieving the geometry of the image and the number of pixels: ::
+
+    >>> camera.shape
+    (512, 512)
+    >>> camera.size
+    262144
+
+Retrieving statistical information about gray values: ::
+
+    >>> camera.min(), camera.max()
+    (0, 255)
+    >>> camera.mean()
+    118.31400299072266
+
+Numpy arrays representing images can be of different integer of float
+numerical types. See :ref:`data_types` for more information about data
+types.
+
+Numpy indexing can be used both for looking at pixel values, and to
+modify pixel values: ::
+
+    >>> # Value of pixel on 10th line and 20th column
+    >>> camera[10, 20]
+    153
+    >>> # Turn to black pixel on 3rd line and 10th column
+    >>> camera[3, 10] = 0
+
+Be careful that the first dimension (``camera.shape[0]``) corresponds to
+lines, while the second dimension (``camera.shape[1]``) stands for
+columns.
+
+Beyond individual pixels, it is possible to access / modify values of
+whole sets of pixels, using the different indexing possibilities of
+NumPy.
+
+Slicing::
+
+    >>> # Set to black the ten first lines
+    >>> camera[:10] = 0
+
+Masking (indexing with masks of booleans)::
+
+    >>> mask = camera < 87
+    >>> # Set to "white" (255) pixels where mask is True
+    >>> camera[mask] = 255
+
+Fancy indexing (indexing with sets of indices) ::
+
+    >>> inds_x = np.arange(len(camera))
+    >>> inds_y = 4 * inds_x % len(camera)
+    >>> camera[inds_x, inds_y] = 0
+
+Using masks, especially, is very useful to select a set of pixels on
+which to perform further manipulations. The mask can be any boolean array
+of same shape as the image (or at least a shape broadcastable to the
+image shape). This can be useful to define a region of interest, as a
+disk: ::
+
+    >>> l_x, l_y = camera.shape[0], camera.shape[1]
+    >>> X, Y = np.ogrid[:l_x, :l_y]
+    >>> outer_disk_mask = (X - l_x / 2)**2 + (Y - l_y / 2)**2 < (l_x / 2)**2
+    >>> camera[outer_disk_mask] = 0
+
+.. image:: ../../_images/plot_camera_numpy_1.png
+    :width: 45%
+    :target: ../auto_examples/plot_camera_numpy.html
+
+Boolean arithmetics can be used to define more complex masks: ::
+
+    >>> lower_half = X > l_x / 2
+    >>> lower_half_disk = np.logical_and(lower_half, outer_disk_mask)
+    >>> camera = data.camera()
+    >>> camera[lower_half_disk] = 0