label2rgb

Convert label matrix into RGB image

Syntax

RGB = label2rgb(L)

RGB = label2rgb(L,cmap)

RGB = label2rgb(L,cmap,zerocolor)

RGB = label2rgb(L,cmap,zerocolor,colorAssignment)

RGB = label2rgb(___,OutputFormat=outputFormat)

Description

RGB = label2rgb(L) converts a label image, L into an RGB color image for the purpose of visualizing the labeled regions. The label2rgb function determines the color to assign to each object based on the number of objects in the label matrix. The label2rgb function picks colors from the entire range of the colormap.

RGB = label2rgb(L,cmap) specifies the colormap cmap to be used in the RGB image.

RGB = label2rgb(L,cmap,zerocolor) specifies the RGB color of the background elements (pixels labeled 0).

RGB = label2rgb(L,cmap,zerocolor,colorAssignment) controls how label2rgb assigns colors to regions in the label matrix.

RGB = label2rgb(___,OutputFormat=outputFormat) enables you to specify that the function return a list of unique colors instead of an RGB image.

Examples

Use Color to Highlight Elements in Label Matrix

Read and display an image.

I = imread("rice.png"); 
imshow(I)

Create a label matrix from the image.

BW = imbinarize(I); 
CC = bwconncomp(BW);
L = labelmatrix(CC);

Convert the label matrix into an RGB image, using default settings. Background pixels are white.

RGB = label2rgb(L);
imshow(RGB)

Convert the label matrix into an RGB image, specifying optional parameters. This example uses the "spring" colormap, sets background pixels to the color cyan, and randomizes how colors are assigned to the labels.

RGB2 = label2rgb(L,"spring","c","shuffle"); 
imshow(RGB2)

Input Arguments

L — Label image

matrix of nonnegative integers | categorical matrix

Label image of contiguous regions, specified as one of the following.

• A matrix of nonnegative integers. Pixels labeled 0 are the background. Pixels labeled 1 make up one object; pixels labeled 2 make up a second object; and so on. You can get a numeric label image from labeling functions such as watershed or labelmatrix.

• A categorical matrix.

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

cmap — Colormap

"jet" (default) | c-by-3 matrix | colormap function | handle

Colormap to be used in the generated color image RGB, specified as one of the following.

Value	Description
c-by-3 matrix of data type double	Colormap matrix specifying c colors, each as an RGB triple. c must be greater than or equal to the number of labels, numlabels, in label matrix L. You can compute the number of labels as numlabels = max(L(:)). If c is greater than numlabels, then label2rgb creates the RGB image using only the first numlabels rows in the matrix.
colormap function	Name of a MATLAB® colormap function, such as "jet" or "gray". See colormap for a list of supported colormaps.
colormap handle	Handle of a colormap function, such as @jet or @gray.

zerocolor — Fill color

[1 1 1] ("white") (default) | RGB triplet | hexadecimal color code | color name | short color name

Fill color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. label2rgb applies the fill color to the label 0 for numeric label images or the label <undefined> for categorical label images.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

colorAssignment — Color assignment

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

Color assignment, specified as one of these values.

• "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.

• "contrasting-neighbors" (since R2025a) — Assign a subset of colormap colors to maximize contrast between adjacent regions. Each color can correspond to multiple labels.

outputFormat — Output format

"image" (default) | "triplets"

Output format of the RGB data returned in RGB, specified as one of the following.

• "image" — Return an RGB image. If the size of the input label matrix L is M-by-N, then the size of the output RGB image is M-by-N-by-3.

• "triplets" — Return a list of RGB colors. The size of the output is a C-by-3 matrix containing an RGB triplet for each of the C labels in the input label matrix.

Output Arguments

RGB — RGB data

numeric matrix

RGB data, returned as an numeric matrix.

Data Types: uint8

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• label2rgb supports the generation of C and C++ code (requires MATLAB Coder™). For more information, see Code Generation for Image Processing.

• Input label images of data type categorical are not supported.

• When generating code, for best results when using the standard syntax RGB = label2rgb(L,cmap,zerocolor,colorAssignment):

  • Submit at least two input arguments: the label matrix, L, and the colormap matrix, cmap.

  • cmap must be a c-by-3 matrix of data type double. You cannot specify the name of a MATLAB colormap function or a function handle of a colormap function.

  • If you set the background color zerocolor to the same color as one of the regions, then label2rgb will not issue a warning.

  • If you supply a value for colorAssignment, then it must be "noshuffle".

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• Input label images of data type categorical are not supported.

• When generating code, for best results when using the standard syntax RGB = label2rgb(L,cmap,zerocolor,colorAssignment):

  • Submit at least two input arguments: the label matrix, L, and the colormap matrix, cmap.

  • cmap must be a c-by-3 matrix of data type double. You cannot specify the name of a MATLAB colormap function or a function handle of a colormap function.

  • If you set the background color zerocolor to the same color as one of the regions, then label2rgb will not issue a warning.

  • If you supply a value for colorAssignment, then it must be "noshuffle".

Thread-Based Environment

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

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

Version History

Introduced before R2006a

R2025a: Improve color contrast of adjacent labels

To ensure that adjacent regions have visually distinct colors, specify the colorAssignment argument as the new value "contrasting-neighbors".

R2022b: Generate CUDA code using GPU Coder

label2rgb now supports the generation of optimized CUDA^® code (requires GPU Coder™).

R2021b: Support for thread-based environments

label2rgb now supports thread-based environments.