Accelerating the pace of engineering and science

# step

System object: vision.ShapeInserter
Package: vision

Draw specified shape on image

## Syntax

J = step(shapeInserter,I,PTS)
J = step(shapeInserter,I,PTS,ROI)
J = step(shapeInserter,I,PTS,...,CLR)

## Description

J = step(shapeInserter,I,PTS) draws the shape specified by the Shape property on input image I. The input PTS specify the coordinates for the location of the shape. The shapes are embedded on the output image J.

J = step(shapeInserter,I,PTS,ROI) draws a shape inside an area defined by the ROI input. This applies only when you set the ROIInputPort property to true. The ROI input defines a rectangular area as [x y width height], where [x y] determine the upper-left corner location of the rectangle, and width and height specify the size.

J = step(shapeInserter,I,PTS,...,CLR) draws the shape with the border or fill color specified by the input CLR. This applies when you set the BorderColorSource property or the FillColorSource property to 'Input port'.

 Note:   H specifies the System object™ on which to run this step method.The object performs an initialization the first time the step method is executed. This initialization locks nontunable properties and input specifications, such as dimensions, complexity, and data type of the input data. If you change a nontunable property or an input specification, the System object issues an error. To change nontunable properties or inputs, you must first call the release method to unlock the object.

## Input Arguments

shapeInserter

Shape inserter object with shape and properties specified.

I

Input M-by-N matrix of M intensity values or an M-by-N-by-P matrix of M color values where P is the number of color planes.

• Double-precision floating point

• Single-precision floating point

• Fixed point

• Boolean

• 8-, 16-, and 32-bit signed integer

• 8-, 16-, and 32-bit unsigned integer

PTS

Input matrix coordinates describing location and dimension of shape. This property must be an integer value. If you enter non-integer value, the object rounds it to the nearest integer.

You can specify the type of shape as Rectangles, Lines, Polygons, or Circles. When you specify the type of shape to draw, you must also specify the location. The PTS input specifies the location of the points. The table shows the format for the points input for the different shapes. For a more detailed explanation on how to specify shapes and lines, see Draw Shapes and Lines.

Depending on the shape you choose by setting the Shape property, the input matrix PTS must be in one of the following formats:

ShapeFormat of PTS
LinesM-by-4 matrix of M number of lines.

$\left[\begin{array}{cccc}{x}_{11}& {y}_{11}& {x}_{12}& {y}_{12}\\ {x}_{21}& {y}_{21}& {x}_{22}& {y}_{22}\\ ⋮& ⋮& ⋮& ⋮\\ {x}_{M1}& {y}_{M1}& {x}_{M2}& {y}_{M2}\end{array}\right]$

Each row of the matrix corresponds to a different line, and of the same form as the vector for a single line. L is the number of vertices.
RectanglesM-by-4 matrix of M number of rectangles.

$\left[\begin{array}{cccc}{x}_{1}& {y}_{1}& widt{h}_{1}& heigh{t}_{1}\\ {x}_{2}& {y}_{2}& widt{h}_{2}& heigh{t}_{2}\\ ⋮& ⋮& ⋮& ⋮\\ {x}_{M}& {y}_{M}& widt{h}_{M}& heigh{t}_{M}\end{array}\right]$

Each row of the matrix corresponds to a different rectangle and of the same form as the vector for a single rectangle. The [x y] coordinates correspond to the upper-left corner of the rectangle with respect to the image origin. The width and height must be greater than zero.
Polygons

M-by-2L matrix

$\left[\begin{array}{ccccccc}{x}_{11}& {y}_{11}& {x}_{12}& {y}_{12}& \cdots & {x}_{1L}& {y}_{1L}\\ {x}_{21}& {y}_{21}& {x}_{22}& {y}_{22}& \cdots & {x}_{2L}& {y}_{2L}\\ ⋮& ⋮& ⋮& ⋮& \ddots & ⋮& ⋮\\ {x}_{M1}& {y}_{M1}& {x}_{M2}& {y}_{M2}& \cdots & {x}_{ML}& {y}_{ML}\end{array}\right]$

Each row of the matrix corresponds to a different polygon and of the same form as the vector for a single polygon. L is the number of vertices.

Circles

M-by-3 matrix

$\left[\begin{array}{ccc}{x}_{1}& {y}_{1}& radiu{s}_{1}\\ {x}_{2}& {y}_{2}& radiu{s}_{2}\\ ⋮& ⋮& ⋮\\ {x}_{M}& {y}_{M}& radiu{s}_{M}\end{array}\right]$

Each row of the matrix corresponds to a different circle and of the same form as the vector for a single circle.

The table below shows the data types required for the inputs, I and PTS.

Input image IInput matrix PTS
built-in integerbuilt-in or fixed-point integer
fixed-point integerbuilt-in or fixed-point integer
doubledouble, single, or build-in integer
singledouble, single, or build-in integer

RGB

Scalar, vector, or matrix describing one plane of the RGB input video stream.

ROI

Input 4-element vector of integers [x y width height], that define a rectangular area in which to draw the shapes. The first two elements represent the one-based coordinates of the upper-left corner of the area. The second two elements represent the width and height of the area.

• Double-precision floating point

• Single-precision floating point

• 8-, 16-, and 32-bit signed integer

• 8-, 16-, and 32-bit unsigned integer

CLR

This port can be used to dynamically specify shape color.

P-element vector or an M-by-P matrix, where M is the number of shapes, and P, the number of color planes. You can specify a color (RGB), for each shape, or specify one color for all shapes. The data type for the CLR input must be the same as the input image.

## Output Arguments

 J Output image. The shapes are embedded on the output image.
Was this topic helpful?