STY: Rename visualize_boundaries to highlight_boundaries

Add @deprecated decorator to ease the transition.

doc/examples/plot_segmentations.py

@@ -63,8 +63,8 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 from skimage.data import lena
-from skimage.segmentation import felzenszwalb, \
-    visualize_boundaries, slic, quickshift
+from skimage.segmentation import felzenszwalb, slic, quickshift
+from skimage.segmentation import highlight_boundaries
 from skimage.util import img_as_float
 
 img = img_as_float(lena()[::2, ::2])
@@ -80,11 +80,11 @@ fig, ax = plt.subplots(1, 3)
 fig.set_size_inches(8, 3, forward=True)
 plt.subplots_adjust(0.05, 0.05, 0.95, 0.95, 0.05, 0.05)
 
-ax[0].imshow(visualize_boundaries(img, segments_fz))
+ax[0].imshow(highlight_boundaries(img, segments_fz))
 ax[0].set_title("Felzenszwalbs's method")
-ax[1].imshow(visualize_boundaries(img, segments_slic))
+ax[1].imshow(highlight_boundaries(img, segments_slic))
 ax[1].set_title("SLIC")
-ax[2].imshow(visualize_boundaries(img, segments_quick))
+ax[2].imshow(highlight_boundaries(img, segments_quick))
 ax[2].set_title("Quickshift")
 for a in ax:
     a.set_xticks(())

skimage/_shared/utils.py

@@ -0,0 +1,43 @@
+import warnings
+import functools
+
+
+__all__ = ['deprecated']
+
+
+class deprecated(object):
+    """Decorator to mark deprecated functions with warning.
+
+    Adapted from <http://wiki.python.org/moin/PythonDecoratorLibrary>.
+
+    Parameters
+    ----------
+    alt_func : str
+        If given, tell user what function to use instead.
+    behavior : {'warn', 'raise'}
+        Behavior during call to deprecated function: 'warn' = warn user that
+        function is deprecated; 'raise' = raise error.
+    """
+
+    def __init__(self, alt_func=None, behavior='warn'):
+        self.alt_func = alt_func
+        self.behavior = behavior
+
+    def __call__(self, func):
+
+        msg = "Call to deprecated function `%s`." % func.__name__
+        if self.alt_func is not None:
+            msg = msg + " Use `%s` instead." % self.alt_func
+
+        @functools.wraps(func)
+        def wrapped(*args, **kwargs):
+            if self.behavior == 'warn':
+                warnings.warn_explicit(msg,
+                    category=DeprecationWarning,
+                    filename=func.func_code.co_filename,
+                    lineno=func.func_code.co_firstlineno + 1)
+            elif self.behavior == 'raise':
+                raise DeprecationWarning(msg)
+            return func(*args, **kwargs)
+
+        return wrapped

skimage/segmentation/__init__.py

@@ -2,5 +2,6 @@ from .random_walker_segmentation import random_walker
 from ._felzenszwalb import felzenszwalb
 from ._slic import slic
 from ._quickshift import quickshift
-from .boundaries import find_boundaries, visualize_boundaries
+from .boundaries import (find_boundaries, visualize_boundaries,
+                         highlight_boundaries)
 from ._clear_border import clear_border

skimage/segmentation/boundaries.py

@@ -2,6 +2,7 @@ import numpy as np
 from ..morphology import dilation, square
 from ..util import img_as_float
 from ..color import gray2rgb
+from .._shared.utils import deprecated
 
 
 def find_boundaries(label_img):
@@ -12,7 +13,7 @@ def find_boundaries(label_img):
     return boundaries
 
 
-def visualize_boundaries(image, label_img, color=(1, 1, 0), outline_color=None):
+def highlight_boundaries(image, label_img, color=(1, 1, 0), outline_color=None):
     """Return image with boundaries between labeled regions highlighted.
 
     Parameters
@@ -37,3 +38,8 @@ def visualize_boundaries(image, label_img, color=(1, 1, 0), outline_color=None):
         image[outer_boundaries != 0, :] = np.array(outline_color)
     image[boundaries, :] = np.array(color)
     return image
+
+
+@deprecated('highlight_boundaries')
+def visualize_boundaries(*args, **kwargs):
+    return highlight_boundaries(*args, **kwargs)