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 control signals indicate a new active region of the frame. The 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 new frame, or select the frame location in real time via an input argument. You can select more than one region. Define each region by the upper-left corner coordinates and the 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. The diagram shows the output frames for three requested regions. The second output region (treetops) does not include the inactive region above the frame.

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. The object accepts and returns 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.

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.

Construction

ROI = visionhdl.ROISelector returns a System object, ROI, that selects a default region of the active frame from an input stream.

ROI = visionhdl.ROISelector(Name,Value) returns a System object, ROI, with additional options specified by one or more Name,Value pair arguments. Name is a property name and Value is the corresponding value. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Properties not specified retain their default values.

Properties

RegionsSource

Location of the output region definitions.

'Property — Specify the regions in the Regions property.

'Input port' — Specify the regions using arguments to the step method. Each argument is a 1-by-4 vector specifying coordinates for a single region. The object captures the value of the region input ports when it receives vStart set to true in the input control structure.

Default: 'Property'

Regions

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

N is the number of regions. You can select up to 16 regions. The four elements that define each region are the top-left starting coordinates and the dimensions, [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. The regions are independent of each other, so they can overlap. This property applies when you set RegionsSource to 'Property'.

Default: [100 100 50 50]

NumberofRegions

Number of region arguments to the step method, specified as a positive integer.

You can select up to 16 regions. This property applies when you set RegionsSource to 'Input port'.

Default: 1

Methods

step	Return next pixel in reselected frame

Common to All System Objects
`release`	Allow System object property value changes

Examples

collapse all

Select Region of Interest

Open Live Script

Select a fixed region of interest (ROI) from an input frame.

Load a source image from a file.

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 the top-left corner and the dimensions.

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

roicoin = 
  visionhdl.ROISelector with properties:

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

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

Note: This syntax runs only in R2016b or later. If you are using an earlier release, replace each call of an object with the equivalent step syntax. For example, replace myObject(x) with step(myObject,x).

[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 format matching the new region. Convert the pixel stream to an image frame by calling step on 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

Algorithm

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

Latency

The object has a latency of three cycles. The object returns the output pixel and associated control signals on the third call to the step method after the pixel value was applied.

Documentation