Merge pull request #320 from ahojnnes/pyramids-fix

Rename pyramid functions.

doc/examples/plot_pyramid.py

@@ -3,22 +3,23 @@
 Build image pyramids
 ====================
 
-The `build_gauassian_pyramid` function takes an image and yields successive
-images shrunk by a constant scale factor. Image pyramids are often used, e.g.,
-to implement algorithms for denoising, texture discrimination, and scale-
-invariant detection.
+The `pyramid_gaussian` function takes an image and yields successive images
+shrunk by a constant scale factor. Image pyramids are often used, e.g., to
+implement algorithms for denoising, texture discrimination, and scale- invariant
+detection.
+
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 
 from skimage import data
-from skimage.transform import build_gaussian_pyramid
+from skimage.transform import pyramid_gaussian
 
 
 image = data.lena()
 rows, cols, dim = image.shape
-pyramid = tuple(build_gaussian_pyramid(image, downscale=2))
+pyramid = tuple(pyramid_gaussian(image, downscale=2))
 
 composite_image = np.zeros((rows, cols + cols / 2, 3), dtype=np.double)
 

skimage/transform/__init__.py

@@ -8,4 +8,4 @@ from ._geometric import (warp, warp_coords, estimate_transform,
                          PiecewiseAffineTransform)
 from ._warps import swirl, homography, resize, rotate
 from .pyramids import (pyramid_reduce, pyramid_expand,
-                       build_gaussian_pyramid, build_laplacian_pyramid)
+                       pyramid_gaussian, pyramid_laplacian)

skimage/transform/pyramids.py

@@ -135,13 +135,17 @@ def pyramid_expand(image, upscale=2, sigma=None, order=1,
     return out
 
 
-def build_gaussian_pyramid(image, max_layer=-1, downscale=2, sigma=None,
-                           order=1, mode='reflect', cval=0):
+def pyramid_gaussian(image, max_layer=-1, downscale=2, sigma=None, order=1,
+                     mode='reflect', cval=0):
     """Yield images of the gaussian pyramid formed by the input image.
 
     Recursively applies the `pyramid_reduce` function to the image, and yields
-    the downscaled images. Note that the first image of the pyramid will be the
-    original, unscaled image.
+    the downscaled images.
+
+    Note that the first image of the pyramid will be the original, unscaled
+    image. The total number of images is `max_layer + 1`. In case all layers are
+    computed, the last image is either a one-pixel image or the image where the
+    reduction does not change its shape.
 
     Parameters
     ----------
@@ -209,12 +213,20 @@ def build_gaussian_pyramid(image, max_layer=-1, downscale=2, sigma=None,
         yield layer_image
 
 
-def build_laplacian_pyramid(image, max_layer=-1, downscale=2, sigma=None,
-                            order=1, mode='reflect', cval=0):
+def pyramid_laplacian(image, max_layer=-1, downscale=2, sigma=None, order=1,
+                      mode='reflect', cval=0):
     """Yield images of the laplacian pyramid formed by the input image.
 
     Each layer contains the difference between the downsampled and the
-    downsampled plus smoothed image.
+    downsampled, smoothed image::
+
+        layer = resize(prev_layer) - smooth(resize(prev_layer))
+
+    Note that the first image of the pyramid will be the difference between the
+    original, unscaled image and its smoothed version. The total number of
+    images is `max_layer + 1`. In case all layers are computed, the last image
+    is either a one-pixel image or the image where the reduction does not change
+    its shape.
 
     Parameters
     ----------

skimage/transform/tests/test_pyramids.py

@@ -1,7 +1,7 @@
 from numpy.testing import assert_array_equal, run_module_suite
 from skimage import data
 from skimage.transform import (pyramid_reduce, pyramid_expand,
-                               build_gaussian_pyramid, build_laplacian_pyramid)
+                               pyramid_gaussian, pyramid_laplacian)
 
 
 image = data.lena()
@@ -21,7 +21,7 @@ def test_pyramid_expand():
 
 def test_build_gaussian_pyramid():
     rows, cols, dim = image.shape
-    pyramid = build_gaussian_pyramid(image, downscale=2)
+    pyramid = pyramid_gaussian(image, downscale=2)
 
     for layer, out in enumerate(pyramid):
         layer_shape = (rows / 2 ** layer, cols / 2 ** layer, dim)
@@ -30,7 +30,7 @@ def test_build_gaussian_pyramid():
 
 def test_build_laplacian_pyramid():
     rows, cols, dim = image.shape
-    pyramid = build_laplacian_pyramid(image, downscale=2)
+    pyramid = pyramid_laplacian(image, downscale=2)
 
     for layer, out in enumerate(pyramid):
         layer_shape = (rows / 2 ** layer, cols / 2 ** layer, dim)

viewer_examples/viewers/collection_viewer.py

@@ -21,11 +21,11 @@ home/end keys
 import numpy as np
 from skimage import data
 from skimage.viewer import CollectionViewer
-from skimage.transform import build_gaussian_pyramid
+from skimage.transform import pyramid_gaussian
 
 
 img = data.lena()
-img_collection = tuple(build_gaussian_pyramid(img))
+img_collection = tuple(pyramid_gaussian(img))
 
 view = CollectionViewer(img_collection)
 view.show()