insertObjectAnnotation

Annotate truecolor or grayscale image or video stream

Syntax

RGB = insertObjectAnnotation(I,shape,position,label)

insertObjectAnnotation(I,"rectangle",position,label)

insertObjectAnnotation(I,"circle",position,label)

___ = insertObjectAnnotation(___,Name=Value)

Description

RGB = insertObjectAnnotation(I,shape,position,label) returns a truecolor image annotated with shape and label at the location specified by position.

insertObjectAnnotation(I,"rectangle",position,label) inserts rectangles and labels at the location indicated by the position matrix.

insertObjectAnnotation(I,"circle",position,label) inserts circles and corresponding labels at the location indicated by the position matrix.

___ = insertObjectAnnotation(___,Name=Value) specifies options using one or more name-value arguments in addition to the previous syntax. For example,insertObjectAnnotation(I,"rectangle",position,label_str,FontSize=18) sets the annotation font size to 18.

Examples

Annotate Image with Numbers and Strings

Read image.

I = imread("board.tif");

Create labels of floating point numbers. The floating point numbers relate to confidence value labels.

label_str = cell(3,1);
conf_val = [85.212 98.76 78.342];
for ii=1:3
    label_str{ii} = ['Confidence: ' num2str(conf_val(ii),'%0.2f') '%'];
end

Set the position for the rectangles in the form of [x y width height].

position = [23 373 60 66;35 185 77 81;77 107 59 26];

Insert the labels.

RGB = insertObjectAnnotation(I,"rectangle",position,label_str,TextBoxOpacity=0.9,FontSize=18);

Display the annotated image.

figure
imshow(RGB)
title("Annotated chips");

Annotate Image with Integer Numbers

Read an image into the workspace.

I = imread("coins.png");

Set the positions on the image for the circle shapes. The first two values represents the center at (x,y) and the third value is the radius.

position = [96 146 31;236 173 26];

Set the label to display the integers 5 and 10 (U.S. cents).

label = [5 10];

Insert the annotations.

RGB = insertObjectAnnotation(I,"circle",position,label,LineWidth=3,Color=["cyan","yellow"],TextColor="black");

Display.

figure
imshow(RGB)
title("Annotated coins");

Input Arguments

I — Truecolor or grayscale image

M-by-N-by-3 truecolor | M-by-N 2-D grayscale image

Truecolor or grayscale image, specified as an image or video stream. The input image can be either an M-by-N-by-3 truecolor or a M-by-N 2-D grayscale image.

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

shape — Shape of annotation

"rectangle" | "circle" | "projected-cuboid"

Shape of annotation, specified as "rectangle" or "circle"

Data Types: char

position — Position of shape

matrix | vector | cell array

Position of shape, specified according to the type of shape, described in the table.

Shape	Position	Example
"rectangle"	For one or more rectangles, specify M-by-4 matrix where each row specifies a rectangle as $$\left[\begin{array}{cccc}x& y& width& height\end{array}\right]$$. $$\left[\begin{array}{cccc}{x}_1& y_1& widt{h}_1& heigh{t}_1\\ x_2& y_2& widt{h}_2& heigh{t}_2\\ ⋮& ⋮& ⋮& ⋮\\ x_M& y_M& widt{h}_M& heigh{t}_M\end{array}\right]$$	Two rectangles, M=2
"circle"	An M-by-3 matrix, where each row is a vector specifying a circle as $$\left[\begin{array}{ccc}x& y& radius\end{array}\right]$$. The $$\left[\begin{array}{cc}x& y\end{array}\right]$$ coordinates represent the center of the circle. $$\left[\begin{array}{ccc}{x}_1& y_1& radiu{s}_1\\ x_2& y_2& radiu{s}_2\\ ⋮& ⋮& ⋮\\ x_M& y_M& radiu{s}_M\end{array}\right]$$
"projected-cuboid"	An 8-by-2-by-M array or an M-by-8 matrix, where M specifies a projected cuboid. When specified as an 8-by-2-M array, each row must contain the $$\left[\begin{array}{cc}x& y\end{array}\right]$$ location of a projected cuboid vertex. The vertices are connected to form a cuboid with six faces. The order of the input vertices must match the order shown in the diagram. When specified as an M-by-8 matrix, each row specifies the front-facing and rear-facing sides of a projected cuboid in the form, $$\left[\begin{array}{cccccccc}x1& y1& w1& h1& x2& y2& w2& h2\end{array}\right]$$ where, [x1 y1] and [x2 y2] specify the upper-left coordinates of the front-facing and back-facing sides, respectively. [w1 h1] and [w2 h2] specify the corresponding width and height.

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

label — Label to associate with a shape

M-element numeric vector | string | categorical labels | cell array of ASCII character vectors

Label to associate with a shape, specified as an M numeric vector, string, categorical labels, or a cell array of ASCII character vectors. The character, string, or categorical labels must be encoded as ASCII characters. The cell array must be the of length equal to the number of shape positions. You can specify a scalar label for all shapes as a numeric scalar, string, or categorical.

Example: label = [5 10], where the function marks the first shape with the label, 5, and the second shape with the label, 10.

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.

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

Example: Color="white" sets the color for the label text box to white.

Font — Font face of text

"LucidaSansRegular" (default) | character vector | string scalar

Font face of text, specified as a character vector. The font face must be one of the available truetype fonts installed on your system. To get a list of available fonts on your system, type listTrueTypeFonts at the MATLAB^® command prompt.

Data Types: char

FontSize — Label text font size

12 (default) | integer in the range of [8 72]

Label text font size, specified as an integer that corresponds to points in the range of [8 72].

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

LineWidth — Shape border line width

1 (default)

Shape border line width, specified as a positive scalar integer in pixels.

Color — Shape color

"green" (default) | character vector | cell array of character vectors | string scalar | string array | M-by-3 matrix

Shape color, specified as a character vector, cell array of character vectors, vector, or an M-by-3 matrix. You can specify a different color for each shape or one color for all shapes. Color values must be specified in the range [0,255]. Values that have a range of [0,1] must be scaled by a value of 255 before using it with this function. For example, [255 255 255].*colorvalue.

Supported colors are: "blue", "green", "red", "cyan", "magenta", "yellow","black", and "white".

Color	Format	Example
Specify one color for all shapes	String or character color name	"r" "red"
	1-by-3 vector (RGB triplet)	[255 0 0]
Specify a color for each shape	M-element vector	["red","yellow","blue"]
	M-by-3 matrix, as a list of RGB values	255 0 0 255 0 0 0 255 255

Data Types: cell | char | uint8 | uint16 | int16 | double | single

TextColor — Color of text in text label

"black" (default) | character vector | string scalar | [R G B] vector | cell array | string array | M-by-3 matrix

Color of text in text label, specified as a character vector, an [R G B] vector, a cell array, or an M-by-3 matrix. To specify one color for all text, set this parameter to either a character vector or an [R G B] vector. To specify a color for each of the M text labels, set this parameter to a cell array of M character vectors. Alternatively, you can specify an M-by-3 matrix of RGB values for each annotation. RGB values must be in the range of the input image data type.

Supported colors: "blue", "yellow","green", "cyan", "red", "magenta", "black", and "white".

Data Types: char | uint8 | uint16 | int16 | double | single | cell

TextBoxOpacity — Opacity of text label box background

0.6 (default) | range of [0 1]

Opacity of text label box background, specified as a scalar defining the opacity of the background of the label text box. Specify this value in the range of 0 to 1.

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

Output Arguments

RGB — Truecolor or grayscale image with annotation

M-by-N-by-3 truecolor

Truecolor image with annotation, returned as an image or video stream.

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

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Input image must be bounded. See Specify Upper Bounds for Variable-Size Arrays (MATLAB Coder).

• See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2012b

R2022b: Visualize projected cuboids

Added support to visualize projected cuboids.