superpixels3

3-D superpixel oversegmentation of 3-D image

Syntax

[L,NumLabels] = superpixels3(A,N)

[L,NumLabels] = superpixels3(A,N,Name,Value)

Description

[L,NumLabels] = superpixels3(A,N) computes 3-D superpixels of the 3-D image A. N specifies the number of superpixels you want to create. The function returns L, a 3-D label matrix, and NumLabels, the actual number of superpixels returned.

[L,NumLabels] = superpixels3(A,N,Name,Value) computes superpixels of image A using name-value arguments to control aspects of the segmentation.

Examples

Compute 3-D Superpixels of Input Volumetric Intensity Image

Load 3-D MRI data, remove any singleton dimensions, and convert the data into a grayscale intensity image.

load mri;
D = squeeze(D);
A = ind2gray(D,map);

Calculate the 3-D superpixels. Form an output image where each pixel is set to the mean color of its corresponding superpixel region.

[L,N] = superpixels3(A,34);

Show all xy-planes progressively with superpixel boundaries.

imSize = size(A);

Create a stack of RGB images to display the boundaries in color.

imPlusBoundaries = zeros(imSize(1),imSize(2),3,imSize(3),'uint8');
for plane = 1:imSize(3)
  BW = boundarymask(L(:, :, plane));
  % Create an RGB representation of this plane with boundary shown
  % in cyan.
  imPlusBoundaries(:, :, :, plane) = imoverlay(A(:, :, plane), BW, 'cyan');
end

implay(imPlusBoundaries,5)

Set the color of each pixel in output image to the mean intensity of the superpixel region. Show the mean image next to the original. If you run this code, you can use implay to view each slice of the MRI data.

pixelIdxList = label2idx(L);
meanA = zeros(size(A),'like',D);
for superpixel = 1:N
     memberPixelIdx = pixelIdxList{superpixel};
     meanA(memberPixelIdx) = mean(A(memberPixelIdx));
end
implay([A meanA],5);

Input Arguments

A — Volume to segment

3-D numeric array

Volume to segment, specified as a 3-D numeric array.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32

N — Desired number of superpixels

positive integer

Desired number of superpixels, specified as a positive integer.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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: B = superpixels3(A,100,NumIterations=20);

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

Example: B = superpixels3(A,100,"NumIterations",20);

Compactness — Shape of superpixels

positive number

Shape of superpixels, specified as a positive number. A higher value makes the superpixels more regularly shaped, that is, more square. A lower value makes the superpixels adhere to boundaries better, making them irregularly shaped. Typical values are in the range [0.01, 0.1]. The default value for the slic0 method is 0.001 and the default value for the slic method is 0.05.

Note

If you specify the "slic0" method, you typically do not need to adjust the Compactness argument. With the "slic0" method, superpixel3 adaptively refines the Compactness argument automatically, thus eliminating the need to determine a good value.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Method — Algorithm used to compute superpixels

"slic0" (default) | "slic"

Algorithm used to compute the superpixels, specified as one of the following values. For more information, see Algorithms.

Value	Meaning
"slic0"	superpixels3 uses the SLIC0 algorithm to refine Compactness adaptively after the first iteration. This is the default.
"slic"	Compactness is constant during clustering.

Data Types: char | string

NumIterations — Number of iterations

10 (default) | positive integer

Number of iterations used in the clustering phase of the algorithm, specified as a positive integer. For most problems, it is not necessary to adjust this parameter.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

L — Label matrix

3-D array of positive integers

Label matrix, returned as a 3-D array of positive integers. The value 1 indicates the first region, 2 the second region, and so on for each superpixel region in the image.

Data Types: double

NumLabels — Number of superpixels computed

positive number

Number of superpixels computed, returned as a positive number.

Data Types: double

Algorithms

The algorithm used in superpixels3 is a modified version of the Simple Linear Iterative Clustering (SLIC) algorithm used by superpixels. At a high level, it creates cluster centers and then iteratively alternates between assigning pixels to the closest cluster center and updating the locations of the cluster centers. superpixels3 uses a distance metric to determine the closest cluster center for each pixel. This distance metric combines intensity distance and spatial distance.

The function's Compactness argument comes from the mathematical form of the distance metric. The compactness parameter of the algorithm is a scalar value that controls the shape of the superpixels. The distance between two pixels i and j, where m is the compactness value, is:

$$\begin{array}{l}{d}_{\mathrm{int}ensity}=\sqrt{{\left(l_i-l_j\right)}^2}\\ d_{spatial}=\sqrt{{(x_i-x_j)}^2+{(y_i-y_j)}^2+{(z_i-z_j)}^2}\\ D=\sqrt{{(\frac{d_{\mathrm{int}ensity}}{m})}^2+{(\frac{d_{spatial}}{S})}^2}\end{array}$$

Compactness has the same meaning as in the 2-D superpixels function: It determines the relative importance of the intensity distance and the spatial distance in the overall distance metric. A lower value makes the superpixels adhere to boundaries better, making them irregularly shaped. A higher value makes the superpixels more regularly shaped. The dynamic range of input images is normalized within the algorithm to be from 0 to 1. This enables a consistent meaning of compactness values across images.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2016b

R2022b: Support for thread-based environments

superpixels3 now supports thread-based environments.