visionhdl.ROISelector

Select region of interest (ROI) from pixel stream

Description

The visionhdl.ROISelector System object™ selects a portion of the active frame from a video stream. The total size of the frame remains the same. The output control signals indicate a new active region of the frame. This diagram shows the inactive pixel regions in blue and the requested output region outlined in orange.

You can specify a fixed size and location for the ROI, or you can select the frame location dynamically by using an input argument. You can select more than one region. Define each region by specifying its upper-left corner coordinates and dimensions. The object returns one set of pixels and control signals for each region you specify. The object sets the inactive pixels in the output frame to zero.

Regions are independent from each other, so they can overlap. If you specify a region that includes the edge of the active frame, the object returns only the active portion of the region. This diagram shows the output frames for three requested regions. The second output region does not include the inactive region above the frame.

The object also provides a mode for vertical reuse. In this mode, you must specify regions that have no vertical overlap and are aligned in columns. Each column of regions shares one output pixel stream. The control signals define each region in the stream. This arrangement enables parallel processing of each column, and the reuse of downstream processing logic for each region in a column. To use this mode, set the VerticalReuse property to true. Use the visionhdlframetoregions function to divide a frame into tiled regions for vertical reuse.

To select regions of interest (ROIs) from a pixel stream:

1. Create the visionhdl.ROISelector object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

ROI = visionhdl.ROISelector(Name,Value)

Description

ROI = visionhdl.ROISelector(Name,Value) creates a System object that selects regions of the active frame from an input stream. Set properties using one or more name-value pairs. Enclose each property name in single quotes. For example,.'Regions',[1 1 32 24] configures the object to select a 32-by-24 pixel region in the top-left corner of the frame.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

VerticalReuse — Option to return one pixel stream for each column of regions

false (default) | true

Option to return one pixel stream for each column of regions, specified as false or true. When you set this property to true, you must specify regions that have no vertical overlap and that are aligned in columns. The object has one output pixel stream for each column of regions. This arrangement enables parallel processing of each column and the reuse of downstream processing logic for each region in a column. Use the visionhdlframetoregions function to divide a frame into tiled regions for vertical reuse.

Dependencies

To enable this property, set the RegionsSource property to 'Property'.

RegionsSource — Location of output region definitions

'Property' (default) | 'Input port'

Location of the output region definitions, specified as one of these values:

'Property' — Specify the regions by using the Regions property.

'Input port' — Specify the regions by using input arguments to the object. Each input argument is a four-element row vector corresponding to one region. The object captures the value of the region input arguments when it receives vStart set to true in the input control structure.

Dependencies

To enable this property, set the VerticalReuse property to false.

Regions — Rectangular ROIs to select from input frame

[100 100 50 50] (default) | R-by-4 matrix

Rectangular regions of interest to select from the input frame, specified as an R-by-4 matrix.

R is the number of regions. The four elements that define each region are the top-left starting coordinates and dimensions of the region and must be of the form [hPos vPos hSize vSize]. The coordinates count from the upper-left corner of the active frame, defined as [1,1]. hSize must be greater than 1.

When you set the VerticalReuse property to false, the regions are independent of each other, so they can overlap. R must not be greater than 16.

When you set the VerticalReuse property to true, the regions in this matrix must have no vertical overlap and be aligned in columns. This diagram shows two examples of invalid regions outlined with a blue dashed line. The region on the left overlaps another region vertically. The two regions at the bottom do not align with the other regions in their columns. The regions do not have to cover the entire frame. Pixels outside of the tiled regions are marked as inactive pixels. The number of columns must not be greater than 16.

Dependencies

To enable this parameter, set the RegionsSource property to 'Property'.

NumberOfRegions — Number of region input arguments

1 (default) | integer in the range [1, 16]

Number of region input arguments to the object, specified as an integer in the range [1, 16].

Dependencies

To enable this parameter, set the RegionsSource property to 'Input port'.

Usage

Syntax

[pixel1,ctrl1] = ROI(pixelin,ctrlin)

[pixel1,ctrl1,...,pixelR,ctrlR] = ROI(pixelin,ctrlin)

[pixel1,ctrl1,...,pixelR,ctrlR] = ROI(pixelin,ctrlin,region1,...,regionR)

Description

[pixel1,ctrl1] = ROI(pixelin,ctrlin) returns the next pixel value, pixel1, and control signals, ctrl1, resulting from masking the active image frame into a single new region. Define the region by setting the Regions property to a four-element row vector, [hPos vPos hSize vSize].

[pixel1,ctrl1,...,pixelR,ctrlR] = ROI(pixelin,ctrlin) returns the next pixel values, pixel1,...,pixelR, and control signals, ctrl1,...,ctrlR, of each stream resulting from masking the active image frame. When you set the VerticalReuse property to false, each output stream contains one active region, and the number of streams is the NumberOfRegions property value or the number of rows in the Regions matrix. When you set the VerticalReuse property to true, each output stream contains a set of vertically-aligned regions. In both cases, define the regions by setting the Regions property to an R-by-4 matrix of ROI coordinates.

[pixel1,ctrl1,...,pixelR,ctrlR] = ROI(pixelin,ctrlin,region1,...,regionR) returns the next pixel values of each stream, pixel1,...,pixelR, resulting from masking the active image frame into 1 to R new regions, as directed by the region1,...,regionR arguments. Each region input is a four-element row vector of ROI coordinates. Use this syntax when you set the RegionsSource property to 'Input Port', and the NumberOfRegions property to R.

This object uses a streaming pixel interface with a structure for frame control signals. This interface enables the object to operate independently of image size and format and to connect with other Vision HDL Toolbox™ objects. The object accepts and returns a scalar pixel value and control signals as a structure containing five signals. The control signals indicate the validity of each pixel and its location in the frame. To convert a pixel matrix into a pixel stream and control signals, use the visionhdl.FrameToPixels object. For a description of the interface, see Streaming Pixel Interface.

Input Arguments

pixelin — Input pixel stream

scalar

Single image pixel in a pixel stream, specified as a scalar value representing intensity.

You can simulate System objects with a multipixel streaming interface, but you cannot generate HDL code for System objects that use multipixel streams. To generate HDL code for multipixel algorithms, use the equivalent Simulink^® blocks.

The software supports double and single data types for simulation, but not for HDL code generation.

Data Types: uint | int | fi | logical | double | single

ctrlin — Control signals accompanying input pixel stream

pixelcontrol structure

Control signals accompanying the input pixel stream, specified as a pixelcontrol structure containing five logical data type signals. The signals describe the validity of the pixel and its location in the frame. For more details, see Pixel Control Structure.

Data Types: struct

region1,...,regionR — Region of interest

four-element row vector

Region of interest, specified as a row vector of four positive integers that define the coordinates of the top-left corner and dimensions of each desired output frame. The vector must have the form [hPos vPos hSize vSize]. Specify R region arguments, where R is the NumberOfRegions property value.

Dependencies

To enable this argument, set the VerticalReuse property to false and set the RegionsSource property to 'Input Port'.

Data Types: int | uint

Output Arguments

pixel1,...,pixelR — Output pixel stream

scalar

Output pixel, returned as a scalar value. The output data type is the same data type as the input pixelin argument. By default, the number of output pixel arguments is the NumberOfRegions property value, or the number of rows in the Regions property matrix. When you set VerticalReuse to true, the object has one output pixel argument for each column of vertically-aligned regions.

Data Types: uint | int | fi | logical | double | single

ctrl1,...,ctrlR — Pixel stream control signals

structure

Pixel stream control signals indicating the validity of each output pixel and its location within the frame, returned as a structure of five logical signals. For more details, see Pixel Control Structure.

By default, the number of output control arguments is the NumberOfRegions property value, or the number of rows in the Regions property matrix. When you set VerticalReuse to true, the object has one output control argument for each column of vertically-aligned regions.

Data Types: struct

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Select Fixed ROI from Input Frame

Load a source image from a file, and then display the image.

frmOrig = imread('coins.png');
[frmActiveLines,frmActivePixels] = size(frmOrig);
imshow(frmOrig)
title 'Input Image'

Create a serializer object and define inactive pixel regions.

frm2pix = visionhdl.FrameToPixels( ...
      'NumComponents',1, ...
      'VideoFormat','custom', ...
      'ActivePixelsPerLine',frmActivePixels, ...
      'ActiveVideoLines',frmActiveLines, ...
      'TotalPixelsPerLine',frmActivePixels+20, ...
      'TotalVideoLines',frmActiveLines+20, ...
      'StartingActiveLine',3, ...     
      'FrontPorch',10);

Create an object to select a region of interest. Define a rectangular region by the coordinates of its top-left corner and dimensions.

hPos = 80;
vPos = 60;
hSize = 65;
vSize = 50;
roicoin = visionhdl.ROISelector('Regions',[hPos vPos hSize vSize])

roicoin = 
  visionhdl.ROISelector with properties:

    VerticalReuse: false
    RegionsSource: 'Property'
          Regions: [80 60 65 50]

Serialize the test image by calling the serializer object. pixIn is a vector of intensity values. ctrlIn is a vector of control signal structures.

[pixIn,ctrlIn] = frm2pix(frmOrig);

Prepare to process pixels by preallocating output vectors. The output frame is the same size as the input frame, but the control signals indicate a different active region.

[~,~,numPixelsPerFrame] = getparamfromfrm2pix(frm2pix);
pixOut = uint8(zeros(numPixelsPerFrame,1));
ctrlOut = repmat(pixelcontrolstruct,numPixelsPerFrame,1);

For each pixel in the padded frame, apply the region mask.

for p = 1:numPixelsPerFrame  
    [pixOut(p),ctrlOut(p)] = roicoin(pixIn(p),ctrlIn(p));
end

Create a deserializer object with a format that matches the new region. Convert the pixel stream to an image frame by calling the deserializer object. Display the resulting image.

pix2frm = visionhdl.PixelsToFrame( ...
      'NumComponents',1, ...
      'VideoFormat','custom', ...
      'ActivePixelsPerLine',hSize, ...
      'ActiveVideoLines',vSize, ...
      'TotalPixelsPerLine',hSize+20);
[frmOutput,frmValid] = pix2frm(pixOut,ctrlOut);
if frmValid
    figure
    imshow(frmOutput)
    title 'Output Image'
end

Algorithms

The generated HDL code for the visionhdl.ROISelector System object uses two 32-bit counters. The object does not use additional counters for additional regions.

Latency

The object has a latency of three cycles.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

This System object supports C/C++ code generation for accelerating MATLAB^® simulations, and for DPI component generation. For more information about acceleration, see Accelerate Pixel-Streaming Designs Using MATLAB Coder. For more information about DPI component generation, see Considerations for DPI Component Generation with MATLAB (HDL Verifier).

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

To generate HDL code from Vision HDL Toolbox System objects, see Design Hardware-Targeted Image Filters in MATLAB.

Version History

Introduced in R2016a

R2021a: Multipixel-multicomponent streaming

The block now supports streams that are both multipixel and multicomponent. The object supports input and output matrices of NumPixels-by-NumComponents pixels, where NumPixels is 2, 4, or 8. The ctrl argument remains scalar, and the control signals in the pixelcontrol structure apply to all pixels in the matrix.

R2021a: Resource sharing

The object now provides an option to share hardware resources when you select vertically aligned regions. Regions in the same column share the same pixelcontrol structure output.

Set the VerticalReuse property to true, and provide a set of regions that are aligned in columns and do not overlap vertically within each column. You can specify up to 1024 regions per column. To divide a frame into tiled regions that are compatible with vertical reuse, use the visionhdlframetoregions function.