# imsegkmeans3

K-means clustering based volume segmentation

## Description

uses name-value pairs to control aspects of the k-means clustering algorithm.`L`

= imsegkmeans3(`V`

,`k`

,`Name,Value`

)

## 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.

*
Before R2021a, use commas to separate each name and value, and enclose*
`Name`

*in quotes.*

**Example: **`'NumAttempts',5`

`NormalizeInput`

— Normalize input data

`true`

or `1`

(default) | `false`

or `0`

Normalize input data to zero mean and unit variance, specified as the
comma-separated pair consisting of `'NormalizeInput'`

and 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 the comma-separated pair consisting of
`'NumAttempts'`

and a positive integer.

`MaxIterations`

— Maximum number of iterations

`100`

(default) | positive integer

Maximum number of iterations, specified as the comma-separated pair consisting of
`'MaxIterations'`

and a positive integer.

`Threshold`

— Accuracy threshold

`1e-4`

(default) | positive number

Accuracy threshold, specified as the comma-separated pair consisting of
`'Threshold'`

and 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.

Class 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**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)