From 29212a31a7b5a53dec731a4c30252c05c89019f6 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Thu, 22 Aug 2013 16:43:36 +0200 Subject: [PATCH] Some additions to the user guide: getting started section + section on common numpy operations. --- doc/examples/plot_camera_numpy.py | 29 +++++++++ doc/source/user_guide.txt | 2 + doc/source/user_guide/getting_started.txt | 45 +++++++++++++ doc/source/user_guide/numpy_images.txt | 77 +++++++++++++++++++++++ 4 files changed, 153 insertions(+) create mode 100644 doc/examples/plot_camera_numpy.py create mode 100644 doc/source/user_guide/getting_started.txt create mode 100644 doc/source/user_guide/numpy_images.txt diff --git a/doc/examples/plot_camera_numpy.py b/doc/examples/plot_camera_numpy.py new file mode 100644 index 00000000..36d4be34 --- /dev/null +++ b/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() diff --git a/doc/source/user_guide.txt b/doc/source/user_guide.txt index 178e130d..338d9984 100644 --- a/doc/source/user_guide.txt +++ b/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 diff --git a/doc/source/user_guide/getting_started.txt b/doc/source/user_guide/getting_started.txt new file mode 100644 index 00000000..1d480990 --- /dev/null +++ b/doc/source/user_guide/getting_started.txt @@ -0,0 +1,45 @@ +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 +`_ webpage. + +Within ``scikit-image``, images are represented as NumPy arrays, for +example 2-D arrays for grayscale 2-D images :: + + >>> type(camera) + + >>> # An image with 512 rows and 512 columns + >>> camera.shape + (512, 512) + +The :mod:`skimage.data` submodule provides a set of functions returning +model images, that can be used to get started quickly on using +scikit-image's functions: :: + + >>> coins = data.coins() + >>> from skimage import filter + >>> threshold_value = filter.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) + diff --git a/doc/source/user_guide/numpy_images.txt b/doc/source/user_guide/numpy_images.txt new file mode 100644 index 00000000..dd93db90 --- /dev/null +++ b/doc/source/user_guide/numpy_images.txt @@ -0,0 +1,77 @@ +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 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 corresponds to lines, while the +second dimension (fastest varying dimension) 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