Main Content

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.

Specified region of the input frame returned as a pixel stream with pixels outside of the region marked as inactive.

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.

Three regions (one partially falling outside the active frame, and one overlapping another), returned as three pixel streams.

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.

Eight tiled regions returned as two pixel streams that each contain four vertically-aligned regions.

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

expand all

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.

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

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.

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

N 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. N 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'.

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,...,pixelN,ctrlN] = ROI(pixelIn,ctrlIn)
[pixel1,ctrl1,...,pixelN,ctrlN] = ROI(pixelIn,ctrlIn,region1,...,regionN)

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,...,pixelN,ctrlN] = ROI(pixelIn,ctrlIn) returns the next pixel values, pixel1,...,pixelN, and control signals, ctrl1,...,ctrlN, 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 N-by-4 matrix of ROI coordinates.

[pixel1,ctrl1,...,pixelN,ctrlN] = ROI(pixelIn,ctrlIn,region1,...,regionN) returns the next pixel values of each stream, pixel1,...,pixelN, resulting from masking the active image frame into 1 to N new regions, as directed by the region1,...,regionN 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 N.

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 full description of the interface, see Streaming Pixel Interface.

Input Arguments

expand all

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

double and single data types are supported for simulation, but not for HDL code generation.

Data Types: uint8 | uint16 | uint32 | int8 | int16 | int32 | fi | logical | double | single

Control signals accompanying 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

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 N region arguments, where N is the NumberOfRegions property value.

Dependencies

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

Data Types: int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

expand all

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.

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)

expand all

stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

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);
[frmOutput,frmValid] = pix2frm(pixOut,ctrlOut);
if frmValid
    figure
    imshow(frmOutput)
    title 'Output Image'
end

Algorithms

expand all

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.

Introduced in R2016a