insertShape

Insert shapes in image or video

Syntax

RGB = insertShape(I,shape,position)

RGB = insertShape(___,Name=Value)

Description

RGB = insertShape(I,shape,position) insert the specified shape into the truecolor or grayscale image I. The function draws the shapes by overwriting pixel values, and returns a truecolor image.

example

RGB = insertShape(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments from the input arguments from the previous syntax. For example, LineWidth=5 sets the line width value to 5 of the inserted shapes.

Examples

collapse all

Insert Circle and Filled Shapes onto Image

Open Live Script

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,"filled-polygon",{pos_triangle pos_hexagon}, ...
    ShapeColor=["white","green"],Opacity=0.7);

Display the resulting image.

imshow(RGB)

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

`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` — Type of shape
`"rectangle"` | `"filled-rectangle"` | `"line"` | `"polygon"` | `"filled-polygon"` | `"circle"` | `"filled-circle"` | `"projected-cuboid"` | `"ellipse"` | `"filled-ellipse"`

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

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

Shape	Position	Definition
`rectangle` `filled-rectangle`	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 $[\begin{matrix} x & y & w i d t h & h e i g h t \end{matrix}]$ . 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. $[\begin{matrix} x_{1} & y_{1} & w i d t h_{1} & h e i g h t_{1} \\ x_{2} & y_{2} & w i d t h_{2} & h e i g h t_{2} \\ ⋮ & ⋮ & ⋮ & ⋮ \\ x_{M} & y_{M} & w i d t h_{M} & h e i g h t_{M} \end{matrix}]$
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]. M is the number of rotated rectangles. xctr and yctr specify the center of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis before rotation. h 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 rectangle.
`circle` `filled-circle`	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]. M is the number of circles. xctr and yctr specify the center of the circle. radius specifies the radius of the circle. $[\begin{matrix} x c t r_{1} & y c t r_{1} & r a d i u s_{1} \\ x c t r_{2} & y c t r_{2} & r a d i u s_{2} \\ ⋮ & ⋮ & ⋮ \\ x c t r_{M} & y c t r_{M} & r a d i u s_{M} \end{matrix}]$
`ellipse` `filled-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] M is the number of ellipses. xctr and yctr specify the center of the ellipse. major and minor are the lengths of the major and minor ellipse axes, respectively. yaw is the angle of rotation in degrees. The angle of rotation is clockwise positive around the center of the ellipse.
`line`	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. Single lines with connected endpoints — Specify as a P-by-2 matrix, where each row specifies an endpoint in the form [x y], and the endpoint in one row connects directly to the endpoint in the next. P is the number of endpoints in the line. Multiple lines with the same number of endpoints — Specify as an M-by-2P matrix, where each row specifies the consecutive endpoints of a single line in the form [x1 y1 x2 y2 ... xp yp]. Each [x y] pair is the coordinates of a single endpoint. M is the number of specified lines, and P is the number of endpoints per line. Multiple lines with different numbers of endpoints — Specify as an M-by-1 cell array, where each cell contains the endpoints for a single line as a P-by-2 matrix or a 1-by-2P vector]. M is the number of specified lines, and P is the number of endpoints for each line
`polygon` `filled-polygon`	For one or more polygons, specify in spatial coordinates as an M-by-1 cell array, where 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 [x₁, y₁, x₂,y₂, … x_L,y_L ]. M is the number of polygons. Each [x y] pair describes a vertex location or endpoint. L is the number of vertices in a polygon or endpoints in a line. Each polygon or line can have a different number of vertices or endpoints.
`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.

rectangle

filled-rectangle

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 $[\begin{matrix} x & y & w i d t h & h e i g h t \end{matrix}]$ .

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.

$[\begin{matrix} x_{1} & y_{1} & w i d t h_{1} & h e i g h t_{1} \\ x_{2} & y_{2} & w i d t h_{2} & h e i g h t_{2} \\ ⋮ & ⋮ & ⋮ & ⋮ \\ x_{M} & y_{M} & w i d t h_{M} & h e i g h t_{M} \end{matrix}]$

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

M is the number of rotated rectangles.
xctr and yctr specify the center of the rectangle.
w specifies the width of the rectangle, which is its length along the x-axis before rotation.
h 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 rectangle.

Square rectangle rotated by -30 degrees.

circle

filled-circle

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

M is the number of circles.
xctr and yctr specify the center of the circle.
radius specifies the radius of the circle.

$[\begin{matrix} x c t r_{1} & y c t r_{1} & r a d i u s_{1} \\ x c t r_{2} & y c t r_{2} & r a d i u s_{2} \\ ⋮ & ⋮ & ⋮ \\ x c t r_{M} & y c t r_{M} & r a d i u s_{M} \end{matrix}]$

ellipse

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

M is the number of ellipses.
xctr and yctr specify the center of the ellipse.
major and minor are the lengths of the major and minor ellipse axes, respectively.
yaw is the angle of rotation in degrees. The angle of rotation is clockwise positive around the center of the ellipse.

line

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.

Single lines with connected endpoints — Specify as a P-by-2 matrix, where each row specifies an endpoint in the form [x y], and the endpoint in one row connects directly to the endpoint in the next. P is the number of endpoints in the line.
Multiple lines with the same number of endpoints — Specify as an M-by-2P matrix, where each row specifies the consecutive endpoints of a single line in the form [x1 y1 x2 y2 ... xp yp]. Each [x y] pair is the coordinates of a single endpoint. M is the number of specified lines, and P is the number of endpoints per line.
Multiple lines with different numbers of endpoints — Specify as an M-by-1 cell array, where each cell contains the endpoints for a single line as a P-by-2 matrix or a 1-by-2P vector]. M is the number of specified lines, and P is the number of endpoints for each line

polygon

filled-polygon

For one or more polygons, specify in spatial coordinates as an M-by-1 cell array, where 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 [x₁, y₁, x₂,y₂, … x_L,y_L ].

M is the number of polygons.
Each [x y] pair describes a vertex location or endpoint.
L is the number of vertices in a polygon or endpoints in a line. Each polygon or line can have a different number of vertices or endpoints.

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.

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.

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: 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 | three-column matrix of RGB triplets

Shape 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 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	`"r"` `"red"`
Specify one color for all shapes (or markers)	RGB triplet	`[1 0 0]`
Specify a color for each shape (or marker)	Vector of color names	`["red","yellow","blue"]`
Specify a color for each shape (or marker)	Three-column 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
`"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]`

`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 "filled-rectangle", "filled-polygon", and "filled-circle" shapes.

`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

collapse all

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

The input argument shape must be a compile-time constant.
The ShapeColor and SmoothEdges name-value arguments must be compile-time constants.
Code generation requires a C++ compiler. For a list of supported compilers, see Supported and Compatible Compilers

Version History

Introduced in R2014a

expand all

R2024b: Support for ellipse shape

Added support for "ellipse" and "filled-ellipse" 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 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.

insertShape

Syntax

Description

Examples

Insert Circle and Filled Shapes onto Image

Input Arguments

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`shape` — Type of shape
`"rectangle"` | `"filled-rectangle"` | `"line"` | `"polygon"` | `"filled-polygon"` | `"circle"` | `"filled-circle"` | `"projected-cuboid"` | `"ellipse"` | `"filled-ellipse"`

`position` — Position of shape
matrix | vector | cell array

Name-Value Arguments

`LineWidth` — Shape border line width
`1` (default) | positive integer

`ShapeColor` — Shape color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`Opacity` — Opacity of filled shape
`0.6` (default) | scalar in range [0,1]

`SmoothEdges` — Smooth shape edges
`true` or `1` (default) | `false` or `0`

Output Arguments

`RGB` — Output image
M-by-N-by-3 truecolor image

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

R2024b: Support for ellipse shape

R2023b: Specify RGB color in the range [0,1]

R2023b: Rotated rectangle support for bounding box

R2023b: Show orientation of rectangle of bounding box

R2022b: Visualize projected cuboids

See Also

Functions

Topics

insertShape

Syntax

Description

Examples

Insert Circle and Filled Shapes onto Image

Input Arguments

I — Input image M-by-N-by-3 truecolor image | M-by-N grayscale image

shape — Type of shape "rectangle" | "filled-rectangle" | "line" | "polygon" | "filled-polygon" | "circle" | "filled-circle" | "projected-cuboid" | "ellipse" | "filled-ellipse"

position — Position of shape matrix | vector | cell array

Name-Value Arguments

LineWidth — Shape border line width 1 (default) | positive integer

ShapeColor — Shape color "green" (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

Opacity — Opacity of filled shape 0.6 (default) | scalar in range [0,1]

SmoothEdges — Smooth shape edges true or 1 (default) | false or 0

Output Arguments

RGB — Output image M-by-N-by-3 truecolor image

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

R2024b: Support for ellipse shape

R2023b: Specify RGB color in the range [0,1]

R2023b: Rotated rectangle support for bounding box

R2023b: Show orientation of rectangle of bounding box

R2022b: Visualize projected cuboids

See Also

Functions

Topics

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`shape` — Type of shape
`"rectangle"` | `"filled-rectangle"` | `"line"` | `"polygon"` | `"filled-polygon"` | `"circle"` | `"filled-circle"` | `"projected-cuboid"` | `"ellipse"` | `"filled-ellipse"`

`position` — Position of shape
matrix | vector | cell array

`LineWidth` — Shape border line width
`1` (default) | positive integer

`ShapeColor` — Shape color
`"green"` (default) | short color name | color name | vector of color names | three-column matrix of RGB triplets

`Opacity` — Opacity of filled shape
`0.6` (default) | scalar in range [0,1]

`SmoothEdges` — Smooth shape edges
`true` or `1` (default) | `false` or `0`

`RGB` — Output image
M-by-N-by-3 truecolor image

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.