showShape
Display shapes on image, video, or point cloud
Description
showShape(___,
specifies options using one or more namevalue arguments in addition to the previous syntax.
For example, Name=Value
) showShape("rectangle",bboxes,Color="yellow")
sets the color
for the shapes to yellow.
Examples
Display Detected Objects in Image
Read an image into the workspace.
I = imread("visionteam1.jpg");
Create an aggregate channel features (ACF) people detector.
detector = peopleDetectorACF()
detector = acfObjectDetector with properties: ModelName: 'inria100x41' ObjectTrainingSize: [100 41] NumWeakLearners: 2048
Detect people in the image.
[bboxes,scores] = detect(detector,I);
Display the image with a labeled rectangle. Display the associated detection score around each detected person.
figure imshow(I) labels = "person:"+scores; showShape("rectangle",bboxes,Label=labels)
Display Bounding Box Around Object in Point Cloud
Read point cloud data into the workspace.
ptCloud = pcread("teapot.ply");
Display the point cloud data.
figure pcshow(ptCloud) xlabel("X") ylabel("Y") zlabel("Z")
Define a cuboid and display it in green with an opacity of 0.5
.
pos = [0.3753 0 1.65 6 4 3 0 0 0]; showShape("cuboid",pos,Color="green",Opacity=0.5)
Visualize Cuboid Around Moving Object in Point Cloud Stream
Read point cloud data into the workspace.
ptCloud = pcread("teapot.ply");
Define a rotation matrix and 3D transform to rotate the point cloud, and an associated cuboid, by 5 degrees.
rot = 5; R = [ cosd(rot) sind(rot) 0 0; ... sind(rot) cosd(rot) 0 0; ... 0 0 1 0; ... 0 0 0 1]; tform = affine3d(R);
Compute the x and y rendered limits of the point cloud to ensure that the point cloud is not clipped during rotation.
pcLimits = abs([ptCloud.XLimits ptCloud.YLimits]); maxLimit = max(pcLimits);
Add an additional margin to the plot to prevent the cuboid from being clipped during rotation.
margin = 1; maxLimit = maxLimit + margin; xlimits = [maxLimit maxLimit]; ylimits = [maxLimit maxLimit]; zlimits = ptCloud.ZLimits;
Create a player for visualizing the point cloud.
player = pcplayer(xlimits,ylimits,zlimits);
Customize the player axis labels.
xlabel(player.Axes,"X (m)"); ylabel(player.Axes,"Y (m)"); zlabel(player.Axes,"Z (m)");
Define a cuboid around the point cloud.
cuboidPosition = [0.3753 0 1.65 6 4 3 0 0 0];
Define the output view for a cuboid rotation. Use the same limits as the player so that the cuboid is not clipped. Then, display the rotated point cloud and cuboid.
gridSize = [1 1 1]; ref = imref3d(gridSize,xlimits,ylimits,zlimits); for i = 1:round((360/rot)) % Rotate point cloud. ptCloud = pctransform(ptCloud,tform); % Rotate the cuboid. cuboidPosition = bboxwarp(cuboidPosition,tform,ref); % Show rotated point cloud data. view(player,ptCloud) % Show rotated cuboid. showShape("cuboid",cuboidPosition, ... Parent=player.Axes, ... Color="green", ... Opacity=0.5) % Use drawnow to synchronize point cloud and shape visualization. drawnow end
Input Arguments
shape
— Type of shape
"rectangle"
 "filledrectangle"
 "line"
 "polygon"
 "filledpolygon"
 "circle"
 "filledcircle"
 "projectedcuboid"
Type of shape, specified as "rectangle"
,
"filledrectangle"
, "line"
,
"polygon"
, "filledpolygon"
,
"circle"
, or "filledcircle"
,
"projectedcuboid"
.
Data Types: char
position
— Positions and sizes of shapes
matrix  vector  cell array
Positions and sizes of shapes, specified according to the type of shapes, described in this table.
Bounding Box  Description 

rectangle 
Defined in spatial coordinates as an Mby4 numeric matrix with rows of the form [x y w h], where:

rotatedrectangle 
Defined in spatial coordinates as an Mby5 numeric matrix with rows of the form [xctr yctr xlen ylen yaw], where:

cuboid 
Defined in spatial coordinates as an Mby9 numeric matrix with rows of the form [xctr yctr zctr xlen ylen zlen xrot yrot zrot], where:
The figure shows how these values determine the position of a cuboid. 
circle  Defined in spatial coordinates as an Mby3 numeric matrix with rows of the form [xctr yctr radius], where:

 Defined in spatial coordinates as a Pby2 matrix in which each row is an [x y] endpoint or a 1by2P vector of consecutive endpoints of the from [x_{1} y_{1} x_{2} y_{2} … x_{P} x_{P}].
To specify several lines that contain different numbers of endpoints, you can use the cell array format described for a polygon. 
polygon  Defined in spatial coordinates as an Mby1 cell array in which 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} ], where:

projectedcuboid  An 8by2byM array or an Mby8 matrix, where M specifies a projected cuboid. When specified as an 8by2M 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 Mby8 matrix, each row specifies the frontfacing and rearfacing 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 upperleft coordinates of the frontfacing and backfacing sides, respectively. [w1 h1] and [w2 h2] specify the corresponding width and height. 
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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: showShape("rectangle",bboxes,Color="yellow")
sets the color
for the shapes to yellow.
Label
— Shape label
[]
(default)  scalar  Melement vector  Melement cell array of character vectors
Shape label, specified as a scalar, Melement vector, or an Melement cell array of character vector, where M specifies the number of shapes.
If the input is a scalar value, then the function applies the label to each shape. If the input is an Melement vector or cell array, then the function applies the unique label to the corresponding shape, using the order in which the shapes are specified to the function.
Color
— Shape color
lines(1)
(default)  one or more RGB triplets  one or more color names or short color names
Shape color, specified as one or more RGB triplets, or one or more (MATLAB
ColorSpec
) color or short color names. 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
Color  Format  Example 

Specify one color for all shapes  Color name 

RGB triplet 
 
Specify a color for each shape  Melement vector 

Mby3 matrix, as a list of RGB values  255 0 0 255 0 0 0 255 255 
Opacity
— Opacity of shape fill
0
(default)  Melement vector of values in the range [0 1]
Opacity of the shape fill, specified as an Melement vector of
numeric values in the range [0 1
], where M
specifies the number of shapes. To use the same opacity for all shapes, specify a
scalar opacity value. For a fully opaque shape fill, set Opacity
to 1
.
Parent
— Output axes
gca
(default)  Axes
graphics object
Output axes, specified as an Axes Properties graphics object.
LineColor
— Border line color
'auto'
(default)  one or more RGB triplets  one or more color names or short color names
Border line color, specified as one or more RGB triplets, or one or more color or
short color names. To use the same color for all border lines, specify a single
(MATLAB ColorSpec
) color name or a single RGB triplet.
To use a different color for each shape, specify an Melement vector or cell array of color names or an Mby3 numeric matrix in which each row is an RGB triplet. M is the number of shapes specified to the function.
LineWidth
— Border line width
'auto'
(default)  positive scalar integer  Melement vector of positive values
Border line width in pixels, specified as a positive scalar integer or an Melement vector of positive scalar integers, where M is the number of shapes. To use the same line width for all shapes, specify a positive scalar integer. Otherwise, specify an Melement vector of positive integers.
LineOpacity
— Border line opacity of shape fill
0
(default)  Melement vector of values in the range [0 1]
Border line opacity of the shape fill, specified as an
Melement vector of numeric values in the range [0
1
], where M is the number of shapes. To use the same
opacity for the border line of all shapes, specify a scalar opacity value. For a fully
opaque border line, set Opacity
to 1
.
LabelTextColor
— Label text color
'black
(default)  one or more RGB triplets  one or more color names or short color names
Label text color, specified as one or more RGB triplets, or one or more color
names or short color names. To use the same color for the text of all labels, specify
a single (MATLAB ColorSpec
) color name or a single RGB
triplet.
To use a different color for text of each label, specify an Melement vector or cell array of color names or an Mby3 numeric matrix in which each row is an RGB triplet. M is the number of labels specified to the function.
LabelOpacity
— Label opacity
0
(default)  Melement vector of values in the range [0 1]
Label opacity, specified as an Melement vector of numeric
values in the range [0 1
], where M is the number
of shapes. To use the same opacity for all labels, specify a scalar opacity value. For
a fully opaque label, set Opacity
to 1
.
LabelFont
— Label font
"Helvetica"
(default)  "FixedWidth"
 supported font
Label font, specified as "FixedWidth"
or a font that your
system supports. To display and print text properly, you must select a font that your
system supports. If you select an unsupported font, the function returns an error. If
you specify "FixedWidth"
, the function uses the font specified by
the FixedWidthFont
property of the Root Properties object. The fixedwidth font relies on the value of
get(0,'FixedWidthFontName')
.
LabelFontSize
— Label font size
12
(default)  positive scalar
Label font size in point units, specified as a positive scalar.
Version History
Introduced in R2020bR2022b: Visualize projected cuboids
Added support to visualize projected cuboids.
R2022a: Bounding Box Coordinates: Data augmentation for object detection using spatial coordinates
The bboxresize
,
bboxcrop
,
bboxwarp
, and
showShape
functions assume the input bounding box coordinates for axisaligned rectangles are
specified in spatial coordinates and return the transformed bounding boxes in spatial
coordinates.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
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)