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 | color name | short color name

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

You can specify any color using an RGB triplet. An RGB triplet is a 3-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].

You can specify some common colors by name as a string scalar or character vector. This table lists the named color options and the equivalent RGB triplets.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

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 for these palettes using the orderedcolors function (since R2023b). For example, get the RGB triplets for the "gem" palette.

RGB = orderedcolors("gem");

Example: "r"

Example: "green"

Example: [0 0.4470 0.7410]

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