imoverlay

Burn binary mask into 2-D image

Syntax

B = imoverlay(A,BW)

B = imoverlay(A,BW,color)

Description

B = imoverlay(A,BW) fills the grayscale or RGB image A with a solid color where the input binary mask, BW, is true.

B = imoverlay(A,BW,color) specifies the color that imoverlay uses to fill the image.

Examples

Burn Binary Image into Grayscale Image

Read a grayscale image into the workspace.

A = imread('cameraman.tif');

Read a binary image into the workspace.

BW = imread('text.png');

Burn the binary image into the grayscale image, specifying the color to be used for the binary mask.

B = imoverlay(A,BW,'yellow');

Display the result.

imshow(B)

Burn Binary Image into RGB Image

Read an RGB image into the workspace.

RGB = imread('peppers.png');

Read a binary image into the workspace.

BW = imread('text.png');

Crop the RGB image to make it the same size as the binary mask.

RGB_cropped = imcrop(RGB,[64,128,255,255]);

Burn the binary image into the cropped RGB image, choosing the color to be used.

B = imoverlay(RGB_cropped,BW,'red');

Display the result.

figure
imshow(B)

Input Arguments

A — Input image

2-D grayscale image | 2-D RGB image

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

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

BW — Mask image

2-D binary matrix | 2-D numeric matrix

Mask image, specified 2-D binary matrix or 2-D numeric matrix of the same size as the first two dimensions of image A. For numeric input, any nonzero pixels are considered to be 1 (true).

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

color — Color used for overlay

"yellow" (default) | RGB triplet | hexadecimal color code | color name | short color name

Color used for the overlay, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name.

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

Example: "r"

Example: "green"

Example: [0 0.4470 0.7410]

Example: "#00FFFF"

Output Arguments

B — Output image

2-D RGB image

Output image, returned as a 2-D RGB image.

Data Types: uint8

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

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

• When generating code, if you specify color as a string or character vector, then the value must be a compile-time constant.

GPU Code Generation

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

Usage notes and limitations:

• When generating code, if you specify color as a string or character vector, then the value must be a compile-time constant.

Version History

Introduced in R2016a

R2026a: Specify color using hexadecimal color code

You can now specify the color argument as a hexadecimal color code.