Module: segmentation

skimage.segmentation.clear_border(image[, ...]) Clear objects connected to image border.
skimage.segmentation.felzenszwalb(image[, ...]) Computes Felsenszwalb’s efficient graph based image segmentation.
skimage.segmentation.find_boundaries(label_img) Return bool array where boundaries between labeled regions are True.
skimage.segmentation.join_segmentations(s1, s2) Return the join of the two input segmentations.
skimage.segmentation.mark_boundaries(image, ...) Return image with boundaries between labeled regions highlighted.
skimage.segmentation.quickshift Segments image using quickshift clustering in Color-(x,y) space.
skimage.segmentation.random_walker(data, labels) Random walker algorithm for segmentation from markers.
skimage.segmentation.relabel_from_one(...) Convert labels in an arbitrary label field to {1, ...
skimage.segmentation.slic Segments image using k-means clustering in Color-(x,y) space.
skimage.segmentation.visualize_boundaries(...)

clear_border

skimage.segmentation.clear_border(image, buffer_size=0, bgval=0)

Clear objects connected to image border.

The changes will be applied to the input image.

Parameters :

image : (N, M) array

Binary image.

buffer_size : int, optional

Define additional buffer around image border.

bgval : float or int, optional

Value for cleared objects.

Returns :

image : (N, M) array

Cleared binary image.

Examples

>>> import numpy as np
>>> from skimage.segmentation import clear_border
>>> image = np.array([[0, 0, 0, 0, 0, 0, 0, 1, 0],
...                   [0, 0, 0, 0, 1, 0, 0, 0, 0],
...                   [1, 0, 0, 1, 0, 1, 0, 0, 0],
...                   [0, 0, 1, 1, 1, 1, 1, 0, 0],
...                   [0, 1, 1, 1, 1, 1, 1, 1, 0],
...                   [0, 0, 0, 0, 0, 0, 0, 0, 0]])
>>> clear_border(image)
array([[0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 1, 0, 0, 0, 0],
       [0, 0, 0, 1, 0, 1, 0, 0, 0],
       [0, 0, 1, 1, 1, 1, 1, 0, 0],
       [0, 1, 1, 1, 1, 1, 1, 1, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0]])

felzenszwalb

skimage.segmentation.felzenszwalb(image, scale=1, sigma=0.8, min_size=20)

Computes Felsenszwalb’s efficient graph based image segmentation.

Produces an oversegmentation of a multichannel (i.e. RGB) image using a fast, minimum spanning tree based clustering on the image grid. The parameter scale sets an observation level. Higher scale means less and larger segments. sigma is the diameter of a Gaussian kernel, used for smoothing the image prior to segmentation.

The number of produced segments as well as their size can only be controlled indirectly through scale. Segment size within an image can vary greatly depending on local contrast.

For RGB images, the algorithm computes a separate segmentation for each channel and then combines these. The combined segmentation is the intersection of the separate segmentations on the color channels.

Parameters :

image : (width, height, 3) or (width, height) ndarray

Input image.

scale : float

Free parameter. Higher means larger clusters.

sigma : float

Width of Gaussian kernel used in preprocessing.

min_size : int

Minimum component size. Enforced using postprocessing.

Returns :

segment_mask : (width, height) ndarray

Integer mask indicating segment labels.

References

[R114]Efficient graph-based image segmentation, Felzenszwalb, P.F. and Huttenlocher, D.P. International Journal of Computer Vision, 2004

find_boundaries

skimage.segmentation.find_boundaries(label_img)

Return bool array where boundaries between labeled regions are True.

join_segmentations

skimage.segmentation.join_segmentations(s1, s2)

Return the join of the two input segmentations.

The join J of S1 and S2 is defined as the segmentation in which two voxels are in the same segment in J if and only if they are in the same segment in both S1 and S2.

Parameters :

s1, s2 : numpy arrays

s1 and s2 are label fields of the same shape.

Returns :

j : numpy array

The join segmentation of s1 and s2.

Examples

>>> import numpy as np
>>> from skimage.segmentation import join_segmentations
>>> s1 = np.array([[0, 0, 1, 1],
...                [0, 2, 1, 1],
...                [2, 2, 2, 1]])
>>> s2 = np.array([[0, 1, 1, 0],
...                [0, 1, 1, 0],
...                [0, 1, 1, 1]])
>>> join_segmentations(s1, s2)
array([[0, 1, 3, 2],
       [0, 5, 3, 2],
       [4, 5, 5, 3]])

mark_boundaries

skimage.segmentation.mark_boundaries(image, label_img, color=(1, 1, 0), outline_color=(0, 0, 0))

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.

quickshift

skimage.segmentation.quickshift()

Segments image using quickshift clustering in Color-(x,y) space.

Produces an oversegmentation of the image using the quickshift mode-seeking algorithm.

Parameters :

image : (width, height, channels) ndarray

Input image.

ratio : float, between 0 and 1.

Balances color-space proximity and image-space proximity. Higher values give more weight to color-space.

kernel_size : float

Width of Gaussian kernel used in smoothing the sample density. Higher means fewer clusters.

max_dist : float

Cut-off point for data distances. Higher means fewer clusters.

return_tree : bool

Whether to return the full segmentation hierarchy tree and distances.

sigma : float

Width for Gaussian smoothing as preprocessing. Zero means no smoothing.

convert2lab : bool

Whether the input should be converted to Lab colorspace prior to segmentation. For this purpose, the input is assumed to be RGB.

random_seed : None or int

Random seed used for breaking ties.

Returns :

segment_mask : (width, height) ndarray

Integer mask indicating segment labels.

Notes

The authors advocate to convert the image to Lab color space prior to segmentation, though this is not strictly necessary. For this to work, the image must be given in RGB format.

References

[R115]Quick shift and kernel methods for mode seeking, Vedaldi, A. and Soatto, S. European Conference on Computer Vision, 2008

random_walker

skimage.segmentation.random_walker(data, labels, beta=130, mode='bf', tol=0.001, copy=True, multichannel=False, return_full_prob=False, depth=1.0)

Random walker algorithm for segmentation from markers.

Random walker algorithm is implemented for gray-level or multichannel images.

Parameters :

data : array_like

Image to be segmented in phases. Gray-level data can be two- or three-dimensional; multichannel data can be three- or four- dimensional (multichannel=True) with the highest dimension denoting channels. Data spacing is assumed isotropic unless depth keyword argument is used.

labels : array of ints, of same shape as data without channels dimension

Array of seed markers labeled with different positive integers for different phases. Zero-labeled pixels are unlabeled pixels. Negative labels correspond to inactive pixels that are not taken into account (they are removed from the graph). If labels are not consecutive integers, the labels array will be transformed so that labels are consecutive. In the multichannel case, labels should have the same shape as a single channel of data, i.e. without the final dimension denoting channels.

beta : float

Penalization coefficient for the random walker motion (the greater beta, the more difficult the diffusion).

mode : {‘bf’, ‘cg_mg’, ‘cg’} (default: ‘bf’)

Mode for solving the linear system in the random walker algorithm.

  • ‘bf’ (brute force, default): an LU factorization of the Laplacian is computed. This is fast for small images (<1024x1024), but very slow (due to the memory cost) and memory-consuming for big images (in 3-D for example).
  • ‘cg’ (conjugate gradient): the linear system is solved iteratively using the Conjugate Gradient method from scipy.sparse.linalg. This is less memory-consuming than the brute force method for large images, but it is quite slow.
  • ‘cg_mg’ (conjugate gradient with multigrid preconditioner): a preconditioner is computed using a multigrid solver, then the solution is computed with the Conjugate Gradient method. This mode requires that the pyamg module (http://code.google.com/p/pyamg/) is installed. For images of size > 512x512, this is the recommended (fastest) mode.

tol : float

tolerance to achieve when solving the linear system, in cg’ and ‘cg_mg’ modes.

copy : bool

If copy is False, the labels array will be overwritten with the result of the segmentation. Use copy=False if you want to save on memory.

multichannel : bool, default False

If True, input data is parsed as multichannel data (see ‘data’ above for proper input format in this case)

return_full_prob : bool, default False

If True, the probability that a pixel belongs to each of the labels will be returned, instead of only the most likely label.

depth : float, default 1.

Correction for non-isotropic voxel depths in 3D volumes. Default (1.) implies isotropy. This factor is derived as follows: depth = (out-of-plane voxel spacing) / (in-plane voxel spacing), where in-plane voxel spacing represents the first two spatial dimensions and out-of-plane voxel spacing represents the third spatial dimension.

Returns :

output : ndarray

  • If return_full_prob is False, array of ints of same shape as data, in which each pixel has been labeled according to the marker that reached the pixel first by anisotropic diffusion.
  • If return_full_prob is True, array of floats of shape (nlabels, data.shape). output[label_nb, i, j] is the probability that label label_nb reaches the pixel (i, j) first.

See also

skimage.morphology.watershed
watershed segmentation A segmentation algorithm based on mathematical morphology and “flooding” of regions from markers.

Notes

Multichannel inputs are scaled with all channel data combined. Ensure all channels are separately normalized prior to running this algorithm.

The depth argument is specifically for certain types of 3-dimensional volumes which, due to how they were acquired, have different spacing along in-plane and out-of-plane dimensions. This is commonly encountered in medical imaging. The depth argument corrects gradients calculated along the third spatial dimension for the otherwise inherent assumption that all points are equally spaced.

The algorithm was first proposed in Random walks for image segmentation, Leo Grady, IEEE Trans Pattern Anal Mach Intell. 2006 Nov;28(11):1768-83.

The algorithm solves the diffusion equation at infinite times for sources placed on markers of each phase in turn. A pixel is labeled with the phase that has the greatest probability to diffuse first to the pixel.

The diffusion equation is solved by minimizing x.T L x for each phase, where L is the Laplacian of the weighted graph of the image, and x is the probability that a marker of the given phase arrives first at a pixel by diffusion (x=1 on markers of the phase, x=0 on the other markers, and the other coefficients are looked for). Each pixel is attributed the label for which it has a maximal value of x. The Laplacian L of the image is defined as:

  • L_ii = d_i, the number of neighbors of pixel i (the degree of i)
  • L_ij = -w_ij if i and j are adjacent pixels

The weight w_ij is a decreasing function of the norm of the local gradient. This ensures that diffusion is easier between pixels of similar values.

When the Laplacian is decomposed into blocks of marked and unmarked pixels:

L = M B.T
    B A

with first indices corresponding to marked pixels, and then to unmarked pixels, minimizing x.T L x for one phase amount to solving:

A x = - B x_m

where x_m = 1 on markers of the given phase, and 0 on other markers. This linear system is solved in the algorithm using a direct method for small images, and an iterative method for larger images.

Examples

>>> a = np.zeros((10, 10)) + 0.2*np.random.random((10, 10))
>>> a[5:8, 5:8] += 1
>>> b = np.zeros_like(a)
>>> b[3,3] = 1 #Marker for first phase
>>> b[6,6] = 2 #Marker for second phase
>>> random_walker(a, b)
array([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 2, 2, 2, 1, 1],
       [1, 1, 1, 1, 1, 2, 2, 2, 1, 1],
       [1, 1, 1, 1, 1, 2, 2, 2, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
       [1, 1, 1, 1, 1, 1, 1, 1, 1, 1]], dtype=int32)

relabel_from_one

skimage.segmentation.relabel_from_one(label_field)

Convert labels in an arbitrary label field to {1, ... number_of_labels}.

This function also returns the forward map (mapping the original labels to the reduced labels) and the inverse map (mapping the reduced labels back to the original ones).

Parameters :

label_field : numpy ndarray (integer type)

Returns :

relabeled : numpy array of same shape as ar

forward_map : 1d numpy array of length np.unique(ar) + 1

inverse_map : 1d numpy array of length len(np.unique(ar))

The length is len(np.unique(ar)) + 1 if 0 is not in np.unique(ar)

Examples

>>> import numpy as np
>>> from skimage.segmentation import relabel_from_one
>>> label_field = array([1, 1, 5, 5, 8, 99, 42])
>>> relab, fw, inv = relabel_from_one(label_field)
>>> relab
array([1, 1, 2, 2, 3, 5, 4])
>>> fw
array([0, 1, 0, 0, 0, 2, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 4, 0, 0, 0,
       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
       0, 0, 0, 0, 0, 0, 0, 5])
>>> inv
array([ 0,  1,  5,  8, 42, 99])
>>> (fw[label_field] == relab).all()
True
>>> (inv[relab] == label_field).all()
True

slic

skimage.segmentation.slic()

Segments image using k-means clustering in Color-(x,y) space.

Parameters :

image : (width, height [, 3]) ndarray

Input image.

n_segments : int

The (approximate) number of labels in the segmented output image.

ratio: float :

Balances color-space proximity and image-space proximity. Higher values give more weight to color-space.

max_iter : int

Maximum number of iterations of k-means.

sigma : float

Width of Gaussian smoothing kernel for preprocessing. Zero means no smoothing.

convert2lab : bool

Whether the input should be converted to Lab colorspace prior to segmentation. For this purpose, the input is assumed to be RGB. Highly recommended.

Returns :

segment_mask : (width, height) ndarray

Integer mask indicating segment labels.

Notes

The image is smoothed using a Gaussian kernel prior to segmentation.

References

[R116]Radhakrishna Achanta, Appu Shaji, Kevin Smith, Aurelien Lucchi, Pascal Fua, and Sabine Süsstrunk, SLIC Superpixels Compared to State-of-the-art Superpixel Methods, TPAMI, May 2012.

Examples

>>> from skimage.segmentation import slic
>>> from skimage.data import lena
>>> img = lena()
>>> segments = slic(img, n_segments=100, ratio=10)
>>> # Increasing the ratio parameter yields more square regions
>>> segments = slic(img, n_segments=100, ratio=20)

visualize_boundaries

skimage.segmentation.visualize_boundaries(*args, **kwargs)