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:
Create the
visionhdl.ROISelectorobject and set its properties.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)'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) | N-by-4 matrix
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'.
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,...,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
Output Arguments
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)
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); [frmOutput,frmValid] = pix2frm(pixOut,ctrlOut); if frmValid figure imshow(frmOutput) title 'Output Image' end
