insertShape
Insert shapes in image or video
Description
specifies options using one or more namevalue arguments in addition to the input
arguments from the input arguments from the previous syntax. For example,
RGB
= insertShape(___,Name=Value
)LineWidth=5
sets the line width value to 5
of the
inserted shapes.
Examples
Insert Circle and Filled Shapes onto Image
Read an image into the workspace.
I = imread("peppers.png");
Place a circle on the image with a border line width of 5 pixels.
RGB = insertShape(I,"circle",[150 280 35],LineWidth=5);
Place a filled triangle and a filled hexagon on the image.
pos_triangle = [183 297 302 250 316 297]; pos_hexagon = [340 163 305 186 303 257 334 294 362 255 361 191]; RGB = insertShape(RGB,"filledpolygon",{pos_triangle pos_hexagon}, ... ShapeColor=["white","green"],Opacity=0.7);
Display the resulting image.
imshow(RGB)
Input Arguments
I
— Input image
MbyNby3 truecolor image  MbyN grayscale image
Input image, specified as an MbyNby3 truecolor or an MbyN grayscale image.
Data Types: single
 double
 int16
 uint8
 uint16
shape
— Type of shape
"rectangle"
 "filledrectangle"
 "line"
 "polygon"
 "filledpolygon"
 "circle"
 "filledcircle"
 "projectedcuboid"
 "ellipse"
 "filledellipse"
Type of shape, specified as "rectangle"
,
"filledrectangle"
, "line"
,
"polygon"
, "filledpolygon"
,
"circle"
, "filledcircle"
,
"projectedcuboid"
, "ellipse"
, or
"filledellipse"
.
Data Types: char
 string
position
— Position of shape
matrix  vector  cell array
Position of shape, specified according to the type of shape, as described in the table.
Shape  Position  Definition 

 For one or more axisaligned rectangles or filled rectangles, specify as an Mby4 numeric matrix, where each row specifies a rectangle of the form $$\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}\\ \vdots & \vdots & \vdots & \vdots \\ {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 Mby5 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 Mby3 numeric matrix, where each row specifies a circle of the form [xctr yctr radius].
$$\left[\begin{array}{ccc}xct{r}_{1}& yct{r}_{1}& radiu{s}_{1}\\ xct{r}_{2}& yct{r}_{2}& radiu{s}_{2}\\ \vdots & \vdots & \vdots \\ xct{r}_{M}& yct{r}_{M}& radiu{s}_{M}\end{array}\right]$$
 
 For one or more ellipses, specify in spatial coordinates as an Mby5 matrix, where each row specifies an ellipse of the form [xctr yctr major minor yaw]


 For one or more lines, specify spatial coordinates using one of these formats to specify a single line with connected endpoints, multiple lines with the same number of endpoints, or multiple lines with different numbers of endpoints.
 
 For one or more polygons, specify in spatial coordinates as an Mby1 cell array, where each cell contains an Lby2 matrix of [x y] vertex locations or a 1by2L vector of consecutive vertex locations of the form [x_{1}, y_{1}, x_{2},y_{2}, … x_{L},y_{L} ].


projectedcuboid  For one or more projected cuboids, specify in spatial coordinates as an 8by2byM array or an Mby8 matrix, where M is the number of projected cuboids. When specified as an 8by2byM 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 Mby8 matrix, each row specifies the dimensions of the frontfacing and rearfacing sides of a projected cuboid in the form, [x1 y1 w1 h1 x2 y2 w2 h2], where [x1 y1] and [x2 y2] specify the upperleft coordinates of the frontfacing and rearfacing 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
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: insertShape(I,"circle",position,Color="yellow")
sets the
shape color to yellow.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: insertShape(I,"circle",position,"Color","yellow")
sets the
shape color to yellow.
LineWidth
— Shape border line width
1
(default)  positive integer
Shape border line width, specified as a positive integer, in pixels. This argument applies to
only the "Rectangle"
, "Line"
,
"Polygon"
, and "Circle"
shapes.
Data Types: uint8
 uint16
 int16
 double
 single
ShapeColor
— Shape color
"green"
(default)  short color name  color name  vector of color names  threecolumn matrix of RGB triplets
Shape color, specified as a short color name, color name, vector of color names, threecolumn 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 shape or one color for all shapes. To
specify one color for all markers, specify ShapeColor
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 

Threecolumn matrix of RGB triplets  [1 0 0 0 1 1 1 0 1 1 1 1] 
This table lists the supported shape colors.
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: logical
 uint8
 uint16
 int16
 double
 single
 cell
Opacity
— Opacity of filled shape
0.6
(default)  scalar in range [0,1]
Opacity of a filled shape, specified as a scalar in the range [0 1]. The
Opacity
argument applies to only the
"filledrectangle"
, "filledpolygon"
, and
"filledcircle"
shapes.
Data Types: double
 single
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
SmoothEdges
— Smooth shape edges
true
or 1
(default)  false
or 0
Smooth shape edges, specified as a logical 1
(true
) or
0
(false
). A true
value
enables an antialiasing filter to smooth shape edges. This value applies to only
nonrectangular shapes. When you enable antialiasing requires additional time to draw
the shapes.
Data Types: logical
Output Arguments
RGB
— Output image
MbyNby3 truecolor image
Output image, returned as an MbyNby3 truecolor image.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
The input argument
shape
must be a compiletime constant.The
ShapeColor
andSmoothEdges
namevalue arguments must be compiletime constants.Code generation requires a C++ compiler. For a list of supported compilers, see Supported and Compatible Compilers
Version History
Introduced in R2014aR2024b: Support for ellipse shape
Added support for "ellipse"
and "filledellipse"
to visualize one or more ellipses on top of an image or on video data.
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
namevalue argument to
display the orientation and angle of a rotated rectangle bounding box.
R2022b: Visualize projected cuboids
Added support to visualize projected cuboids.
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)