Merge pull request #354 from tonysyu/highlight-boundaries

Highlight boundaries

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 mark_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(mark_boundaries(img, segments_fz))
 ax[0].set_title("Felzenszwalbs's method")
-ax[1].imshow(visualize_boundaries(img, segments_slic))
+ax[1].imshow(mark_boundaries(img, segments_slic))
 ax[1].set_title("SLIC")
-ax[2].imshow(visualize_boundaries(img, segments_quick))
+ax[2].imshow(mark_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,5 @@ 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, mark_boundaries
 from ._clear_border import clear_border

skimage/segmentation/boundaries.py

@@ -1,19 +1,45 @@
 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):
+    """Return bool array where boundaries between labeled regions are True."""
     boundaries = np.zeros(label_img.shape, dtype=np.bool)
     boundaries[1:, :] += label_img[1:, :] != label_img[:-1, :]
     boundaries[:, 1:] += label_img[:, 1:] != label_img[:, :-1]
     return boundaries
 
 
-def visualize_boundaries(img, label_img):
-    img = img_as_float(img, force_copy=True)
+def mark_boundaries(image, label_img, color=(1, 1, 0), outline_color=None):
+    """Return image with boundaries between labeled regions highlighted.
+
+    Parameters
+    ----------
+    image : (M, N[, 3]) array
+        Grayscale or RGB image.
+    label_img : (M, N) array
+        Label array where regions are marked by different integer values.
+    color : length-3 sequence
+        RGB color of boundaries in the output image.
+    outline_color : length-3 sequence
+        RGB color surrounding boundaries in the output image. If None, no
+        outline is drawn.
+    """
+    if image.ndim == 2:
+        image = gray2rgb(image)
+    image = img_as_float(image, force_copy=True)
+
     boundaries = find_boundaries(label_img)
-    outer_boundaries = dilation(boundaries.astype(np.uint8), square(2))
-    img[outer_boundaries != 0, :] = np.array([0, 0, 0])  # black
-    img[boundaries, :] = np.array([1, 1, 0])  # yellow
-    return img
+    if outline_color is not None:
+        outer_boundaries = dilation(boundaries.astype(np.uint8), square(2))
+        image[outer_boundaries != 0, :] = np.array(outline_color)
+    image[boundaries, :] = np.array(color)
+    return image
+
+
+@deprecated('mark_boundaries')
+def visualize_boundaries(*args, **kwargs):
+    return mark_boundaries(*args, **kwargs)