insertShape

在图像或视频中插入图形

全页折叠

语法

RGB = insertShape(I,shape,position)

RGB = insertShape(___,Name=Value)

说明

RGB = insertShape(I,shape,position) 将指定的 shape 插入到真彩色或灰度图像 I 中。该函数通过覆盖像素值来绘制图形，并返回一张真彩色图像。

示例

RGB = insertShape(___,Name=Value) 除了使用前一种语法中的输入参量外，还通过一个或多个名称-值参量来指定选项。例如，LineWidth=5 将插入的图形的线宽值设置为 5。

示例

全部折叠

将圆形和实心形状插入图像

打开实时脚本

将图像读入工作区。

I = imread("peppers.png");

在图像上绘制一个圆，边框线宽为 5 像素。

RGB = insertShape(I,"circle",[150 280 35],LineWidth=5);

在图像上放置一个实心三角形和一个实心六边形。

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

显示生成的图像。

imshow(RGB)

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

输入参数

全部折叠

`I` — 输入图像
M×N×3 真彩色图像 | M×N 灰度图像

输入图像，指定为 M×N×3 的真彩色图像或 M×N 的灰度图像。

数据类型: single | double | int16 | uint8 | uint16

`shape` — 形状类型
`"rectangle"` | `"filled-rectangle"` | `"line"` | `"polygon"` | `"filled-polygon"` | `"circle"` | `"filled-circle"` | `"projected-cuboid"` | `"ellipse"` | `"filled-ellipse"`

形状类型，指定为 "rectangle"、"filled-rectangle"、"line"、"polygon"、"filled-polygon"、"circle"、"filled-circle"、"projected-cuboid"、"ellipse" 或 "filled-ellipse"。

数据类型: char | string

`position` — 形状的位置
矩阵 | 向量 | 元胞数组

形状的位置，根据表格中所述的形状类型进行指定。

形状位置定义

形状	位置	定义
`rectangle` `filled-rectangle`	对于一个或多个与轴对齐的矩形或填充矩形，请以 M×4 数值矩阵的形式指定，其中每一行指定一个形式为 $[\begin{matrix} x & y & w i d t h & h e i g h t \end{matrix}]$ 的矩形。 M 是轴对齐矩形的数量。 x 和 `y` 指定矩形的左上角。 w 指定矩形的宽度，即矩形沿 x 轴的长度。 h 指定矩形的高度，即矩形沿 y 轴的长度。 $[\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}]$
对于一个或多个旋转后的矩形，请使用 M×5 数值矩阵在空间坐标系中进行指定，其中每一行指定一个形式为 [xctr yctr w h yaw] 的旋转矩形。 M 是旋转矩形的数量。 xctr 和 yctr 指定矩形的中心。 w 指定矩形的宽度，即旋转前矩形沿 x 轴的长度。 h 指定矩形的高度，即旋转前矩形沿 y 轴的长度。 yaw 指定旋转角度（以度为单位）。该旋转是以矩形中心为轴的顺时针正向旋转。
`circle` `filled-circle`	对于一个或多个圆，请将空间坐标指定为一个 M×3 的数值矩阵，其中每一行指定一个形式为 [xctr yctr radius] 的圆。 M 表示圆的个数。 xctr 和 yctr 指定了圆的中心。 radius 指定了圆的半径。 $[\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`	对于一个或多个椭圆，请以 M×5 矩阵的形式在空间坐标系中指定，其中每一行指定一个形式为 [xctr yctr major minor yaw] 的椭圆。 M 表示省略号的数量。 xctr 和 yctr 指定椭圆的中心。 major 和 minor 分别是椭圆长轴和短轴的长度。 yaw 表示旋转角度（单位：度）。旋转角以椭圆中心为基准，顺时针方向为正。
`line`	对于一条或多条线，请使用以下任一格式指定空间坐标，以定义端点相连的单条线、端点数量相同的多条线，或端点数量不同的多条线。端点相连的单线 - 以 P×2 矩阵的形式指定，其中每一行以 [x y] 的形式指定一个端点，且一行中的端点与下一行中的端点直接相连。P 表示该线段的端点数量。具有相同端点数量的多条线段 - 请以 M×2 P 矩阵的形式指定，其中每一行以 [x1 y1 x2 y2 ... xp yp] 的形式指定单条线段的连续端点。每对 [x y] 代表一个端点的坐标。M 表示指定线的数量，P 表示每条线上的端点数量。多条直线，每条直线的端点数量不同 - 请指定为一个 M×1 的元胞数组，其中每个元胞包含单条直线的端点，形式为 P×2 的矩阵或 1×2 的 P 向量。M 表示指定的行数，P 表示每行的端点数
`polygon` `filled-polygon`	对于一个或多个多边形，请使用 M×1 元胞数组在空间坐标系中指定其位置，其中每个元胞包含一个 L×2 矩阵 [x y]，其中包含顶点位置，或者是一个 1×2 的 L 向量，包含连续的顶点位置，形式为 [x₁, y₁, x₂,y₂, … x_L,y_L ]。 M 表示多边形的数量。每对 [x y] 表示一个顶点位置或端点。 L 表示多边形的顶点数或直线的端点数。每个多边形或线段的顶点或端点数量可以不同。
`projected-cuboid`	对于一个或多个投影长方体，请使用空间坐标以 8×2×M 数组或 M-×8 矩阵的形式指定，其中 M 表示投影长方体的数量。当指定为一个 8×2×M 的数组时，每一行必须包含一个投影长方体顶点的 [x y] 位置。这些顶点相互连接，形成了一个有六个面的长方体。输入顶点的顺序必须与图中所示的顺序一致。当指定为一个 M×8 的矩阵时，每一行指定了一个投影长方体的正面和背面的维度，形式为：[x1 y1 w1 h1 x2 y2 w2 h2]，其中 [x1 y1] 和 [x2 y2] 分别指定了该长方体的正面和背面的左上角坐标，而 [w1 h1] 和 [w2 h2] 则指定了相应的宽度和高度。

rectangle

filled-rectangle

对于一个或多个与轴对齐的矩形或填充矩形，请以 M×4 数值矩阵的形式指定，其中每一行指定一个形式为 $[\begin{matrix} x & y & w i d t h & h e i g h t \end{matrix}]$ 的矩形。

M 是轴对齐矩形的数量。
x 和 y 指定矩形的左上角。
w 指定矩形的宽度，即矩形沿 x 轴的长度。
h 指定矩形的高度，即矩形沿 y 轴的长度。

$[\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}]$

对于一个或多个旋转后的矩形，请使用 M×5 数值矩阵在空间坐标系中进行指定，其中每一行指定一个形式为 [xctr yctr w h yaw] 的旋转矩形。

M 是旋转矩形的数量。
xctr 和 yctr 指定矩形的中心。
w 指定矩形的宽度，即旋转前矩形沿 x 轴的长度。
h 指定矩形的高度，即旋转前矩形沿 y 轴的长度。
yaw 指定旋转角度（以度为单位）。该旋转是以矩形中心为轴的顺时针正向旋转。

Square rectangle rotated by -30 degrees.

circle

filled-circle

对于一个或多个圆，请将空间坐标指定为一个 M×3 的数值矩阵，其中每一行指定一个形式为 [xctr yctr radius] 的圆。

M 表示圆的个数。
xctr 和 yctr 指定了圆的中心。
radius 指定了圆的半径。

$[\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

对于一个或多个椭圆，请以 M×5 矩阵的形式在空间坐标系中指定，其中每一行指定一个形式为 [xctr yctr major minor yaw] 的椭圆。

M 表示省略号的数量。
xctr 和 yctr 指定椭圆的中心。
major 和 minor 分别是椭圆长轴和短轴的长度。
yaw 表示旋转角度（单位：度）。旋转角以椭圆中心为基准，顺时针方向为正。

line

对于一条或多条线，请使用以下任一格式指定空间坐标，以定义端点相连的单条线、端点数量相同的多条线，或端点数量不同的多条线。

端点相连的单线 - 以 P×2 矩阵的形式指定，其中每一行以 [x y] 的形式指定一个端点，且一行中的端点与下一行中的端点直接相连。P 表示该线段的端点数量。
具有相同端点数量的多条线段 - 请以 M×2 P 矩阵的形式指定，其中每一行以 [x1 y1 x2 y2 ... xp yp] 的形式指定单条线段的连续端点。每对 [x y] 代表一个端点的坐标。M 表示指定线的数量，P 表示每条线上的端点数量。
多条直线，每条直线的端点数量不同 - 请指定为一个 M×1 的元胞数组，其中每个元胞包含单条直线的端点，形式为 P×2 的矩阵或 1×2 的 P 向量。M 表示指定的行数，P 表示每行的端点数

polygon

filled-polygon

对于一个或多个多边形，请使用 M×1 元胞数组在空间坐标系中指定其位置，其中每个元胞包含一个 L×2 矩阵 [x y]，其中包含顶点位置，或者是一个 1×2 的 L 向量，包含连续的顶点位置，形式为 [x₁, y₁, x₂,y₂, … x_L,y_L ]。

M 表示多边形的数量。
每对 [x y] 表示一个顶点位置或端点。
L 表示多边形的顶点数或直线的端点数。每个多边形或线段的顶点或端点数量可以不同。

projected-cuboid

对于一个或多个投影长方体，请使用空间坐标以 8×2×M 数组或 M-×8 矩阵的形式指定，其中 M 表示投影长方体的数量。

当指定为一个 8×2×M 的数组时，每一行必须包含一个投影长方体顶点的 [x y] 位置。这些顶点相互连接，形成了一个有六个面的长方体。输入顶点的顺序必须与图中所示的顺序一致。

当指定为一个 M×8 的矩阵时，每一行指定了一个投影长方体的正面和背面的维度，形式为：[x1 y1 w1 h1 x2 y2 w2 h2]，其中 [x1 y1] 和 [x2 y2] 分别指定了该长方体的正面和背面的左上角坐标，而 [w1 h1] 和 [w2 h2] 则指定了相应的宽度和高度。

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.

名称-值参数

全部折叠

将可选参量对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

示例: insertShape(I,"circle",position,Color="yellow") 将形状颜色设置为黄色。

如果使用的是 R2021a 之前的版本，请使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: insertShape(I,"circle",position,"Color","yellow") 将形状颜色设置为黄色。

`LineWidth` — 形状边框线宽
`1` (默认) | 正整数

形状边框线宽，以正整数（单位为像素）表示。此参量仅适用于 "Rectangle"、"Line"、"Polygon" 和 "Circle" 这几种形状。

数据类型: uint8 | uint16 | int16 | double | single

`ShapeColor` — 形状颜色
`"green"` (默认) | 短颜色名称 | 颜色名称 | 颜色名称向量 | 由 RGB 三元组组成的三列矩阵

形状颜色，指定为简短颜色名称、颜色名称、颜色名称向量或包含 RGB 三元组的三列矩阵。

“支持的颜色表”中列出的 RGB 强度值范围为 [0, 1]，但您必须指定符合所选数据类型范围的 RGB 三元组。例如，如果将该参量指定为由 uint8 值组成的矩阵，则必须将每个强度值转换为 [0, 255] 范围内的数值。要将所列的强度值转换为 uint8 数据类型，请使用代码 uint8(255*intensity)，其中 intensity 是表格中列出的 RGB 三元组值。

您可以为每个图形指定不同的颜色，也可以为所有图形指定一种颜色。若要为所有标记指定一种颜色，请将 ShapeColor 作为颜色名称或 [R G B] 向量进行指定。

设定	格式	示例
为所有图形（或标记）指定一种颜色	简短颜色名称或颜色名称	`"r"` `"red"`
为所有图形（或标记）指定一种颜色	RGB 三元组	`[1 0 0]`
为每个形状（或标记）指定一种颜色	颜色名称向量	`["red","yellow","blue"]`
为每个形状（或标记）指定一种颜色	由 RGB 三元组组成的三列矩阵	[1 0 0 0 1 1 1 0 1 1 1 1]

下表列出了支持的形状颜色。

颜色名称	短名称	RGB 三元组
`"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` — 填充形状的不透明度
`0.6` (默认) | 取值范围在 [0,1] 之间的标量

填充形状的不透明度，以 [0 1] 范围内的标量值指定。Opacity 参量仅适用于 "filled-rectangle"、"filled-polygon" 和 "filled-circle" 这三种形状。

`SmoothEdges` — 平滑形状边缘
`true` 或 `1` (默认) | `false` 或 `0`

平滑形状边缘，指定为逻辑值 1 (true) 或 0 (false)。true 值可启用抗锯齿滤波器，以平滑形状边缘。此值仅适用于非矩形形状。启用抗锯齿功能时，绘制图形需要额外的时间。

数据类型: logical

输出参量

全部折叠

`RGB` — 输出图像
M×N×3 真彩色图像

输出图像，以 M×N×3 真彩色图像的形式返回。

扩展功能

全部展开

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

输入参量 shape 必须是编译时常量。
ShapeColor 和 SmoothEdges 名称-值参量必须是编译时常量。
代码生成需要一个 C++ 编译器。有关支持的编译器列表，请参阅支持和兼容的编译器

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

请参阅“C/C++ 代码生成”部分中的用法说明和限制。同样的用法说明和限制也适用于 GPU 代码生成。

版本历史记录

在 R2014a 中推出

全部展开

R2024b: 支持椭圆形状

新增了对 "ellipse" 和 "filled-ellipse" 的支持，可在图像或视频数据上显示一个或多个省略号。

R2023b: 请指定 [0,1] 范围内的 RGB 颜色

从 R2023b 版本开始，您可以使用 [0,1] 范围内的 RGB 值来指定标记颜色。

R2023b: 对边界框中旋转矩形的支持

您可以使用 [xctr yctr width height yaw] 这种形式指定一个旋转后的矩形边界框。

R2023b: 显示边界框中矩形的朝向

现在，您可以指定 ShowOrientation 名称-值参量，以显示已旋转矩形边界框的朝向和角度。

R2022b: 可视化投影后的长方体

新增了对投影长方体的可视化支持。

另请参阅

函数

showShape | insertObjectAnnotation | insertObjectMask | insertMarker | insertText | cuboid2img

insertShape

语法

说明

示例

将圆形和实心形状插入图像

输入参数

I — 输入图像 M×N×3 真彩色图像 | M×N 灰度图像

shape — 形状类型 "rectangle" | "filled-rectangle" | "line" | "polygon" | "filled-polygon" | "circle" | "filled-circle" | "projected-cuboid" | "ellipse" | "filled-ellipse"

position — 形状的位置 矩阵 | 向量 | 元胞数组

名称-值参数

LineWidth — 形状边框线宽 1 (默认) | 正整数

ShapeColor — 形状颜色 "green" (默认) | 短颜色名称 | 颜色名称 | 颜色名称向量 | 由 RGB 三元组组成的三列矩阵

Opacity — 填充形状的不透明度 0.6 (默认) | 取值范围在 [0,1] 之间的标量

SmoothEdges — 平滑形状边缘 true 或 1 (默认) | false 或 0

输出参量

RGB — 输出图像 M×N×3 真彩色图像

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

版本历史记录

R2024b: 支持椭圆形状

R2023b: 请指定 [0,1] 范围内的 RGB 颜色

R2023b: 对边界框中旋转矩形的支持

R2023b: 显示边界框中矩形的朝向

R2022b: 可视化投影后的长方体

另请参阅

函数

主题

`I` — 输入图像
M×N×3 真彩色图像 | M×N 灰度图像

`shape` — 形状类型
`"rectangle"` | `"filled-rectangle"` | `"line"` | `"polygon"` | `"filled-polygon"` | `"circle"` | `"filled-circle"` | `"projected-cuboid"` | `"ellipse"` | `"filled-ellipse"`

`position` — 形状的位置
矩阵 | 向量 | 元胞数组

`LineWidth` — 形状边框线宽
`1` (默认) | 正整数

`ShapeColor` — 形状颜色
`"green"` (默认) | 短颜色名称 | 颜色名称 | 颜色名称向量 | 由 RGB 三元组组成的三列矩阵

`Opacity` — 填充形状的不透明度
`0.6` (默认) | 取值范围在 [0,1] 之间的标量

`SmoothEdges` — 平滑形状边缘
`true` 或 `1` (默认) | `false` 或 `0`

`RGB` — 输出图像
M×N×3 真彩色图像

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。