From 29212a31a7b5a53dec731a4c30252c05c89019f6 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Thu, 22 Aug 2013 16:43:36 +0200 Subject: [PATCH 1/4] 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 From ebe1a1865647542cf984029cbd1bda4c6ec74c89 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Sat, 24 Aug 2013 07:53:16 +0200 Subject: [PATCH 2/4] Minor modifications following review by Johannes --- doc/source/user_guide/getting_started.txt | 6 ++---- doc/source/user_guide/numpy_images.txt | 5 +++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/source/user_guide/getting_started.txt b/doc/source/user_guide/getting_started.txt index 1d480990..21ea95a3 100644 --- a/doc/source/user_guide/getting_started.txt +++ b/doc/source/user_guide/getting_started.txt @@ -2,9 +2,7 @@ Getting started --------------- ``scikit-image`` is an image processing Python package that works with -:mod:`numpy` arrays. The package is imported as ``skimage``: - -:: +:mod:`numpy` arrays. The package is imported as ``skimage``: :: >>> import skimage @@ -16,7 +14,7 @@ Most functions of ``skimage`` are found within submodules: :: A list of submodules and functions is found on the `API reference `_ webpage. -Within ``scikit-image``, images are represented as NumPy arrays, for +Within scikit-image, images are represented as NumPy arrays, for example 2-D arrays for grayscale 2-D images :: >>> type(camera) diff --git a/doc/source/user_guide/numpy_images.txt b/doc/source/user_guide/numpy_images.txt index dd93db90..c03f703b 100644 --- a/doc/source/user_guide/numpy_images.txt +++ b/doc/source/user_guide/numpy_images.txt @@ -30,8 +30,9 @@ modify pixel values: :: >>> # 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. +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 From ad3400dd4723bf17f82e272daf04cb29c31b2643 Mon Sep 17 00:00:00 2001 From: emmanuelle Date: Sat, 22 Nov 2014 14:54:46 +0100 Subject: [PATCH 3/4] Changed a link that pointed to a specific release of scikit-image using the "stable" symlink. --- doc/source/user_guide/getting_started.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/getting_started.txt b/doc/source/user_guide/getting_started.txt index 21ea95a3..87a9d287 100644 --- a/doc/source/user_guide/getting_started.txt +++ b/doc/source/user_guide/getting_started.txt @@ -12,7 +12,7 @@ Most functions of ``skimage`` are found within submodules: :: >>> camera = data.camera() A list of submodules and functions is found on the `API reference -`_ webpage. +`_ webpage. Within scikit-image, images are represented as NumPy arrays, for example 2-D arrays for grayscale 2-D images :: From 236274abfda680e08277001f8e8ad6a10f201c32 Mon Sep 17 00:00:00 2001 From: emmanuelle Date: Sat, 22 Nov 2014 18:33:22 +0100 Subject: [PATCH 4/4] =?UTF-8?q?Implemented=20St=C3=A9fan's=20minor=20comme?= =?UTF-8?q?nts.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/source/user_guide/data_types.txt | 1 + doc/source/user_guide/getting_started.txt | 6 +++--- doc/source/user_guide/numpy_images.txt | 4 ++++ 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/source/user_guide/data_types.txt b/doc/source/user_guide/data_types.txt index 43ea8e9b..7d2b9e2f 100644 --- a/doc/source/user_guide/data_types.txt +++ b/doc/source/user_guide/data_types.txt @@ -1,3 +1,4 @@ +.. _data_types: =================================== Image data types and what they mean diff --git a/doc/source/user_guide/getting_started.txt b/doc/source/user_guide/getting_started.txt index 87a9d287..4013e2fa 100644 --- a/doc/source/user_guide/getting_started.txt +++ b/doc/source/user_guide/getting_started.txt @@ -24,12 +24,12 @@ example 2-D arrays for grayscale 2-D images :: (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 +example 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) + >>> from skimage import filters + >>> threshold_value = filters.threshold_otsu(coins) >>> threshold_value 107 diff --git a/doc/source/user_guide/numpy_images.txt b/doc/source/user_guide/numpy_images.txt index c03f703b..60358be5 100644 --- a/doc/source/user_guide/numpy_images.txt +++ b/doc/source/user_guide/numpy_images.txt @@ -21,6 +21,10 @@ Retrieving statistical information about gray values: :: >>> 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: ::