labeloverlay

Overlay label matrix regions on 2-D image

Syntax

B = labeloverlay(A,L)

B = labeloverlay(A,BW)

B = labeloverlay(A,C)

B = labeloverlay(___,Name=Value)

Description

B = labeloverlay(A,L) fuses the input image, A, with a different color for each nonzero label in label matrix L. The labeloverlay function does not fuse background pixels with a color.

B = labeloverlay(A,BW) fuses the input image with a color where mask BW is true. The labeloverlay function does not fuse background pixels (labeled false ) with a color.

B = labeloverlay(A,C) fuses the input image with a different color for each label in categorical matrix C. The labeloverlay function does not fuse pixels of the <undefined> category with a color.

B = labeloverlay(___,Name=Value) computes the fused overlay image, B, using name-value arguments to control aspects of the computation.

Examples

Visualize Segmentation over Color Image

Read an image, then segment it by using the superpixels function.

A = imread("kobi.png");
[L,N] = superpixels(A,20);

Fuse the original image with unique colors for each region in the segmented label matrix. Display the fused image. Some adjacent regions have similar colors, such as the shades of purple over the nose and an eye. Because the colors are similar, it is difficult to determine the boundary of the regions visually.

B = labeloverlay(A,L);
imshow(B)

Improve the color contrast between neighboring regions by specifying the ColorAssignment name-value argument as "contrasting-neighbors". Display the fused image. Only four high-contrast colors are used for labels in this fused image. The high color contrast improves the visibility of region boundaries.

C = labeloverlay(A,L,ColorAssignment="contrasting-neighbors");
imshow(C)

Visualize Binary Mask over Grayscale Image

Read and display a grayscale image.

A = imread("coins.png");
imshow(A)

Create a mask using binary thresholding.

t = graythresh(A);
BW = imbinarize(A,t);
imshow(BW)

Fuse the mask with the original image. Display the fused image.

B = labeloverlay(A,BW);
imshow(B)

Visualize Categorical Labels over Image

Read an image and its segmented label image.

A = imread("yellowlily.jpg");
L = imread("yellowlily-segmented.png");

Convert the numeric label matrix to a categorical matrix. Specify the values and the names for the categories.

C = categorical(L,[1 2 3],["petal" "leaf" "dirt"]);

Fuse the categorical labels with the original image. Display the fused image.

B = labeloverlay(A,C);
imshow(B)

Fuse the original image with only two labels from the categorical segmentation. Change the colormap, increase the opacity of the label, and display the result.

B2 = labeloverlay(A,C,IncludedLabels=["petal" "leaf"], ...
    Colormap="autumn",Transparency=0.25);
imshow(B2)

Input Arguments

A — Input image

2-D grayscale image | 2-D color image

Input image, specified as a 2-D grayscale or color image.

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

L — Labels

matrix of nonnegative integers

Labels, specified as a matrix of nonnegative integers.

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

BW — Mask

logical matrix

Mask, specified as a logical matrix.

Data Types: logical

C — Category labels

categorical matrix

Category labels, specified as a categorical matrix.

Data Types: categorical

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: labeloverlay(A,L,Colormap="hot") displays labels in colors from the "hot" colormap.

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

Example: labeloverlay(A,L,"Colormap","hot") displays labels in colors from the "hot" colormap.

ColorAssignment — Color assignment

"auto" (default) | "noshuffle" | "shuffle" | "contrasting-neighbors"

Since R2025a

Color assignment, specified as one of the values in the table.

Value of Color Assignment	Description	Sample Output
"noshuffle"	Assign colormap colors to label matrix regions in numerical order. Each region has a unique color.
"shuffle"	Assign colormap colors pseudorandomly. Each region has a unique color.
"auto"	Assign colormap colors based on the format of Colormap. By default, labeloverlay shuffles the color order when you specify a colormap by name, and preserves the color order when you specify the colormap as a numeric matrix.	Same as "shuffle" when specifying Colormap as a string, or when using the default value of Colormap. Same as "noshuffle" when specifying Colormap as a numeric matrix.
"contrasting-neighbors"	Assign a subset of colormap colors to maximize contrast between adjacent regions. Each color can correspond to multiple labels.

Colormap — Colormap

"jet" (default) | l-by-3 colormap | string | character vector

Colormap, specified as one of these values:

• An l-by-3 colormap. RGB triplets in each row of the colormap must be normalized to the range [0, 1]. l is the number of labels in label matrix L, binary mask BW, or categorical matrix C.

• A string or character vector corresponding to one of the valid inputs to the colormap function. By default, labeloverlay shuffles the specified colormap so that adjacent labels are more distinct.

Note

If you also specify ColorAssignment as "contrasting-neighbors", then labeloverlay selects a subset of colors from the colormap with high visual contrast.

Example: [0.2, 0.1, 0.5; 0.1, 0.5, 0.8]

Example: "hot"

Data Types: single | double | char | string

IncludedLabels — Labels to display

integer | vector of integers | string | vector of strings

Labels to display in the fused image, specified as one of the following:

• An integer, or vector of integers, in the range [0, max(L(:))]. By default, labeloverlay displays all nonzero labels.

• A string, or vector of strings, corresponding to labels in categorical matrix C. By default, labeloverlay displays all defined categorical labels.

Any label not included in the vector is considered the background. For example, in the vector [1 3 4], the value 2 would be considered the background, if it existed as a label.

Example: [1 3 4]

Example: ["flower","stem"]

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

Transparency — Transparency

0.5 (default) | number in the range [0, 1]

Transparency of displayed labels, specified as a number in the range [0, 1].

• A value of 0 makes the colored labels completely opaque.

• A value of 1 makes the colored labels completely transparent.

Data Types: single | double

Output Arguments

B — Fused image

numeric matrix

Fused image, returned as a numeric matrix of the same size as A.

Data Types: uint8

Version History

Introduced in R2017b

R2025a: Improve color contrast of adjacent labels

The new ColorAssignment name-value argument enables you to control how labeloverlay assigns colors to label regions.

• To ensure that adjacent regions have visually distinct colors, specify the value "contrasting-neighbors".

• To force or prevent labeloverlay from shuffling the order of colors, specify the value "shuffle" or "noshuffle", respectively.