# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# 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

 Note:   Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object™, you can call the object with arguments, as if it were a function. For example, `y = step(obj,x)` and `y = obj(x)` perform equivalent operations.

`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 `I`Input 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?

Watch now