imsegkmeans3

K-means clustering based volume segmentation

Syntax

L = imsegkmeans3(V,k)

[L,centers] = imsegkmeans3(V,k)

L = imsegkmeans3(V,k,Name=Value)

Description

L = imsegkmeans3(V,k) segments volume V into k clusters by performing k-means clustering and returns the segmented labeled output in L.

[L,centers] = imsegkmeans3(V,k) also returns the cluster centroid locations, centers.

L = imsegkmeans3(V,k,Name=Value) uses name-value arguments to control aspects of the k-means clustering algorithm.

Examples

Segment Volume Using k-Means Clustering

Load a 3-D grayscale MRI volume and display it using volshow.

load mristack
volshow(mristack);

Segment the volume into three clusters.

L = imsegkmeans3(mristack,3);

Display the segmented volume using volshow. To explore slices of the segmented volume, use the Volume Viewer app.

figure
volshow(L);

Input Arguments

V — Volume to segment

3-D grayscale volume | 3-D multispectral volume

Volume to segment, specified as a 3-D grayscale volume of size m-by-n-by-p or a 3-D multispectral volume of size m-by-n-by-p-by-c, where p is the number of planes and c is number of channels.

Note

imsegkmeans3 treats 2-D color images like 3-D volumes of size m-by-n-by-3. If you want 2-D behavior, then use the imsegkmeans function.

Data Types: single | int8 | int16 | uint8 | uint16

k — Number of clusters

positive integer

Number of clusters to create, specified as a positive integer.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: L = imsegkmeans3(I,k,NumAttempts=5) repeats the clustering process five times.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: L = imsegkmeans3(I,k,"NumAttempts",5)

NormalizeInput — Normalize input data

true or 1 (default) | false or 0

Normalize input data to zero mean and unit variance, specified as a numeric or logical 1 (true) or 0 (false). If you specify true, then imsegkmeans3 normalizes each channel of the input individually.

NumAttempts — Number of times to repeat the clustering process

3 (default) | positive integer

Number of times to repeat the clustering process using new initial cluster centroid positions, specified as a positive integer.

MaxIterations — Maximum number of iterations

100 (default) | positive integer

Maximum number of iterations, specified as a positive integer.

Threshold — Accuracy threshold

1e-4 (default) | positive number

Accuracy threshold, specified as a positive number. The algorithm stops when each of the cluster centers move less than the threshold value in consecutive iterations.

Output Arguments

L — Label matrix

matrix of positive integers

Label matrix, specified as a matrix of positive integers. Pixels with label 1 belong to the first cluster, label 2 belong to the second cluster, and so on for each of the k clusters. L has the same first three dimensions as volume V. The class of L depends on number of clusters.

Data Type of L	Number of Clusters
uint8	k <= 255
uint16	256 <= k <= 65535
uint32	65536 <= k <= 2^32-1
double	2^32 <= k

centers — Cluster centroid locations

numeric matrix

Cluster centroid locations, returned as a numeric matrix of size k-by-c, where k is the number of clusters and c is the number of channels. centers is the same class as the image I.

Tips

• The function yields reproducible results. The output will not vary in multiple runs given the same input arguments.

References

[1] Arthur, David, and Sergei Vassilvitskii. “K-Means++: The Advantages of Careful Seeding.” In Proceedings of the Eighteenth Annual ACM-SIAM Symposium on Discrete Algorithms, 1027–35. SODA ’07. USA: Society for Industrial and Applied Mathematics, 2007.

Version History

Introduced in R2018b