insertObjectAnnotation
Annotate truecolor or grayscale image or video
Syntax
Description
___ = insertObjectAnnotation(___,
specifies options using one or more name-value arguments in addition to the previous
syntax. For example, Name=Value
)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 |
---|---|---|
| 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 .
| |
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].
| ||
| 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].
| |
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]
|
|
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 |
|
RGB triplet |
| |
Specify a color for each shape (or marker) | Vector of color names |
|
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 R2012bR2024b: 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.
See Also
Functions
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)