Main Content


Annotate truecolor or grayscale image or video stream



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.


collapse all

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') '%'];

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.

title("Annotated chips");

Figure contains an axes object. The axes object with title Annotated chips contains an object of type image.

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


title("Annotated coins");

Figure contains an axes object. The axes object with title Annotated coins contains an object of type image.

Input Arguments

collapse all

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 of annotation, specified as "rectangle" or "circle"

Data Types: char

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

"rectangle"For one or more rectangles, specify M-by-4 matrix where each row specifies a rectangle as [xywidthheight].


Two rectangles, M=2

"circle"An M-by-3 matrix, where each row is a vector specifying a circle as [xyradius]. The [xy] coordinates represent the center of the circle.



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 [xy] 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,


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.

Cuboid showing numbered vertices. The number starts with 1 assigned to the top right corner of the front facing rectangle. Going counter-clockwise 1-4 for the top face of cuboid, then 5-8 for the bottom face. The positive Z-axis goes up, the positive Y-axis goes to the right and the positive X-axis faces forward.

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

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

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

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

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

Specify one color for all shapes

String or character color name



1-by-3 vector (RGB triplet)

[255 0 0]1-by-3 grid, with columns labeled r,g,b respectively.

Specify a color for each shapeM-element vector


M-by-3 matrix, as a list of RGB values

255 0 0
255 0 0
0 255 255
M-by-3 grid, with columns labeled r,g,b respectively.

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

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

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

collapse all

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

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

Extended Capabilities

Version History

Introduced in R2012b

expand all