showShape

Display shapes on image, video, or point cloud

Since R2020b

Syntax

showShape(shape,position)

showShape(___,Name=Value)

Description

showShape(shape,position) displays one or more instances of a shape shape in the current axes at the specified locations position.

showShape(___,Name=Value) specifies options using one or more name-value arguments in addition to the previous syntax. For example, 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: 'inria-100x41'
    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 3-D 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" | "filled-rectangle" | "line" | "polygon" | "filled-polygon" | "circle" | "filled-circle" | "projected-cuboid"

Type of shape, specified as "rectangle", "filled-rectangle", "line", "polygon", "filled-polygon", "circle", or "filled-circle", "projected-cuboid".

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 M-by-4 numeric matrix with rows of the form [x y w h], where: 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.
rotated-rectangle	Defined in spatial coordinates as an M-by-5 numeric matrix with rows of the form [xctr yctr xlen ylen yaw], where: M is the number of rotated rectangles. xctr and yctr specify the center of the rectangle. xlen specifies the width of the rectangle, which is its length along the x-axis before rotation. ylen 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 bounding box.
cuboid	Defined in spatial coordinates as an M-by-9 numeric matrix with rows of the form [xctr yctr zctr xlen ylen zlen xrot yrot zrot], where: M is the number of cuboids. xctr, yctr, and zctr specify the center of the cuboid. xlen, ylen, and zlen specify the length of the cuboid along the x-axis, y-axis, and z-axis, respectively, before rotation. xrot, yrot, and zrot specify the rotation angles of the cuboid around the x-axis, y-axis, and z-axis, respectively. The xrot, yrot, and zrot rotation angles are in degrees about the cuboid center. Each rotation is clockwise-positive with respect to the positive direction of the associated spatial axis. The function computes rotation matrices assuming ZYX order Euler angles [xrot yrot zrot]. The figure shows how these values determine the position of a cuboid.
circle	Defined in spatial coordinates as an M-by-3 numeric matrix with rows of the form [xctr yctr radius], where: M is the number of circles. xctr and yctr specify the center of the circle. radius specifies the radius of the circle.
line	Defined in spatial coordinates as a P-by-2 matrix in which each row is an [x y] endpoint or a 1-by-2P vector of consecutive endpoints of the from [x1 y1 x2 y2 … xP xP]. P is the number of endpoints. [x1 y1], [x2 y2], and xP xP describe endpoints. 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 M-by-1 cell array in which each cell contains an L-by-2 matrix of [x y] vertex locations or a 1-by-2L vector of consecutive vertex locations of the form [x1, y1, x2,y2, … xL,yL ], where: M is the number of polygons. [x1 y1], [x2 y2] describe vertex locations or endpoints. L is the number of vertices in a polygon or endpoints in a line. Each polygon or line can have different number of vertices or endpoints.
projected-cuboid	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 $$\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 M-by-8 matrix, each row specifies the front-facing and rear-facing 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 upper-left coordinates of the front-facing and back-facing sides, respectively. [w1 h1] and [w2 h2] specify the corresponding width and height.

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: showShape("rectangle",bboxes,Color="yellow") sets the color for the shapes to yellow.

Label — Shape label

[] (default) | scalar | M-element vector | M-element cell array of character vectors

Shape label, specified as a scalar, M-element vector, or an M-element 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 M-element 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	"r" "red"
	RGB triplet	[255 0 0]
Specify a color for each shape	M-element vector	["red","yellow","blue"]
	M-by-3 matrix, as a list of RGB values	255 0 0 255 0 0 0 255 255

Opacity — Opacity of shape fill

0 (default) | M-element vector of values in the range [0 1]

Opacity of the shape fill, specified as an M-element 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 M-element vector or cell array of color names or an M-by-3 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 | M-element vector of positive values

Border line width in pixels, specified as a positive scalar integer or an M-element 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 M-element vector of positive integers.

LineOpacity — Border line opacity of shape fill

0 (default) | M-element vector of values in the range [0 1]

Border line opacity of the shape fill, specified as an M-element 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 M-element vector or cell array of color names or an M-by-3 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) | M-element vector of values in the range [0 1]

Label opacity, specified as an M-element 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 fixed-width 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 R2020b

R2022b: 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 axis-aligned rectangles are specified in spatial coordinates and return the transformed bounding boxes in spatial coordinates.