insertObjectAnnotation

Annotate truecolor or grayscale image or video

Syntax

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

___ = insertObjectAnnotation(___,Name=Value)

Description

RGB = insertObjectAnnotation(I,shape,position,label) annotates a grayscale or truecolor image with the specified shape and label at the specified position. The function returns a truecolor image.

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

Examples

Annotate Image with Numbers and Strings

Read an image into the workspace.

I = imread("board.tif");

Create confidence value labels using floating point numbers.

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 positions for the rectangular bounding boxes associated with the labels using the form [x y width height].

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

Insert the labels into the image.

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 Integers

Read an image into the workspace.

I = imread("coins.png");

Set the positions on the image for the circular bounding boxes associated with the labels. The first two values of each row specify the center coordinates of a circle, (x,y) and the third value is the radius.

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

Set the values for the labels to display as 5 and 10, in integers. These values represent US currency in the form of a nickle and dime, respectively.

label = [5 10];

Insert the annotations into the image.

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

Display the annotated image.

figure
imshow(RGB)
title("Annotated Coins")

Input Arguments

I — Input image

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

Input image, specified as an M-by-N-by-3 truecolor or an M-by-N grayscale image.

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

shape — Shape of annotation

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

Shape of the annotation, specified as "rectangle", "circle", "projected-cuboid", or "ellipse". If you specify a "rectangle" annotation be specify the position of either an axis-aligned or rotated rectangle.

Data Types: char | string

position — Position of shape

matrix | vector | cell array

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

Shape	Position	Definition
rectangle	For one or more axis-aligned rectangles or filled rectangles, specify as an M-by-4 numeric matrix, where each row specifies a rectangle of the form $$\left[\begin{array}{cccc}x& y& width& height\end{array}\right]$$. M is the number of axis-aligned rectangles. x and y specify the upper-left corner of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis. h specifies the height of the rectangle, which is its length along the y-axis. $$\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]$$
	For one or more rotated rectangles, specify in spatial coordinates as an M-by-5 numeric matrix, where each row specifies a rotated rectangle of the form [xctr yctr w h yaw]. M is the number of rotated rectangles. xctr and yctr specify the center of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis before rotation. h specifies the height of the rectangle, which is its length along the y-axis before rotation. yaw specifies the rotation angle in degrees. The rotation is clockwise-positive around the center of the rectangle.
circle	For one or more circles, specify spatial coordinates as an M-by-3 numeric matrix, where each row specifies a circle of the form [xctr yctr radius]. M is the number of circles. xctr and yctr specify the center of the circle. radius specifies the radius of the circle. $$\left[\begin{array}{ccc}xct{r}_1& yct{r}_1& radiu{s}_1\\ xct{r}_2& yct{r}_2& radiu{s}_2\\ ⋮& ⋮& ⋮\\ xct{r}_M& yct{r}_M& radiu{s}_M\end{array}\right]$$
ellipse	For one or more ellipses, specify in spatial coordinates as an M-by-5 matrix, where each row specifies an ellipse of the form [xctr yctr major minor yaw] M is the number of ellipses. xctr and yctr specify the center of the ellipse. major and minor are the lengths of the major and minor ellipse axes, respectively. yaw is the angle of rotation in degrees. The angle of rotation is clockwise positive around the center of the ellipse.
projected-cuboid	For one or more projected cuboids, specify in spatial coordinates as an 8-by-2-by-M array or an M-by-8 matrix, where M is the number of projected cuboids. When specified as an 8-by-2-by-M array, each row must contain the [x y] location of a projected cuboid vertex. The vertices connect 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 dimensions of the front-facing and rear-facing sides of a projected cuboid in the form, [x1 y1 w1 h1 x2 y2 w2 h2], where [x1 y1] and [x2 y2] specify the upper-left coordinates of the front-facing and rear-facing sides, respectively, and [w1 h1] and [w2 h2] specify the corresponding widths and heights.

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

label — Label to associate with shape

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

Label to associate with a shape, specified as an M-element numeric vector, string array, vector of categorical labels, or a cell array of ASCII character vectors. If you use character vectors, string scalars, or categorical labels, you must encode them as ASCII characters. If you specify a cell array, it must be equal in length to the number of specified shape positions. You can specify a single label for all shapes using a numeric scalar, string scalar, or scalar categorical label.

Example: [5 10] 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.

Example: insertObjectAnnotation(I,"rectangle",position,label,FontSize=18); sets the font size to use for inserting annotations to 18.

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

Example: insertObjectAnnotation(I,"rectangle",position,label,"FontSize","18"); sets the font size to use for inserting annotations to 18.

Font — Font face of label text

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

Font face of the label text, specified as a character vector or string scalar. 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, use the listTrueTypeFonts function from the MATLAB^® command prompt.

Data Types: char | string

FontSize — Label text font size

12 (default) | integer in range [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

FontColor — Font color

"black" (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

Font color, specified as a short color name, color name, vector of color names, three-column matrix of RGB triplets.

The supported colors table lists RGB intensities in the range [0, 1], but you must specify RGB triplets in the range of your selected data type. For example, if specifying this argument as a matrix of uint8 values, you must convert each intensity value to the range [0, 255]. To convert the listed intensity values to a uint8 data type, use the code uint8(255*intensity), where intensity is an RGB triplet value listed in the table.

You can specify a different color for each font string or one color for all strings. To specify one color for all strings, specify FontColor as a color name or an [R G B] vector.

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

AnnotationColor — Annotation color

"yellow" (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

Annotation color, specified as a short color name, color name, vector of color names, three-column matrix of RGB triplets.

The supported colors table lists RGB intensities in the range [0, 1], but you must specify RGB triplets in the range of your selected data type. For example, if specifying this argument as a matrix of uint8 values, you must convert each intensity value to the range [0, 255]. To convert the listed intensity values to a uint8 data type, use the code uint8(255*intensity), where intensity is an RGB triplet value listed in the table.

You can specify a different color for each marker or one color for all markers. To specify one color for all markers, specify AnnotationColor as a color name or an [R G B] vector.

Specification	Format	Example
Specify one color for all shapes (or markers)	Short color name or color name	"r" "red"
	RGB triplet	[1 0 0]
Specify a color for each shape (or marker)	Vector of color names	["red","yellow","blue"]
	Three-column matrix of RGB triplets	[1 0 0 0 1 1 1 0 1 1 1 1]

Supported colors are listed in the table.

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]

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

TextBoxOpacity — Opacity of text label box background

0.6 (default) | scalar in the range of [0 1]

Opacity of the text label box background, specified as a scalar in the range of [0, 1]. A value of 0 renders the background of the label text box as fully transparent, while a value of 1 renders it as fully opaque.

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

LineWidth — Shape border line width

1 (default) | positive integer

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

ShowOrientation — Original orientation indicator

0 (false) (default) | 1 (true)

Original orientation indicator, specified as a numeric or logical 1 (true) or 0 (false). A value of 1 (true) displays the original orientation of the rotated rectangle by using an arrow annotation on the bounding box. The original orientation is defined as a zero rotation angle. A value of 0 (false) does not show the arrow annotation.

This argument applies only when Shape describes a rotated rectangle or an ellipse.

Data Types: logical | integer

Output Arguments

RGB — Output image

M-by-N-by-3 truecolor image

Output image, returned as an M-by-N-by-3 truecolor image.

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

• Code generation requires a C++ compiler. For a list of supported compilers, see Supported and Compatible Compilers

Version History

Introduced in R2012b

R2024b: Support for ellipse shape

Added support for "ellipse" to visualize one or more ellipses on top of an image or on video data.

R2024b: Default value for orientation indicator changed from true to false

Starting in R2024b, the default value for the ShowOrientation name-value argument will be false.

R2023b: Specify RGB color in the range [0,1]

Starting in R2023b, you can specify marker color with RGB values in the range [0,1].

R2023b: Rotated rectangle support for bounding box

You can specify a rotated rectangle bounding box using the form [xctr yctr width height yaw].

R2023b: Show orientation of rectangle of bounding box

You can now specify the ShowOrientation name-value argument to display the orientation and angle of a rotated rectangle bounding box.

R2022b: Visualize projected cuboids

Added support to visualize projected cuboids.