Main Content

visionhdl.ImageFilter

2-D FIR filtering

expand all in page

Description

visionhdl.ImageFilter performs two-dimensional finite-impulse-response (FIR) filtering on a pixel stream. It supports the use of programmable filter coefficients.

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

F = visionhdl.ImageFilter returns a System object, F, that performs two-dimensional FIR filtering on an input pixel stream.

F = visionhdl.ImageFilter(Name,Value) returns a 2-D FIR filter System object, F, 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.

F = visionhdl.ImageFilter(coeff,lineSize,Name,Value) returns a 2-D FIR filter System object, F, with the Coefficients property set to coeff, the LineBufferSize property to lineSize, and additional options specified by one or more Name,Value pair arguments.

Input Arguments

coeff

Filter coefficients, specified as a matrix. Each dimension of the matrix must have at least 2 elements and no more than 64 elements. This argument sets the Coefficients property value.

lineSize

Size of the line memory buffer, specified as a power of two that accommodates the number of active pixels in a horizontal line. This argument sets the LineBufferSize property value.

Output Arguments

F

visionhdl.ImageFilter System object

Properties

CoefficientsSource

Select the source for specifying the filter coefficients.

  • 'Property' (default) — Select this value to specify filter coefficients using the Coefficients property.

  • 'Input port' — Select this value to specify filter coefficients using the coeff argument.

Coefficients

Coefficients of the filter, specified as a matrix. Each dimension of the matrix must have at least 2 elements and no more than 64 elements. This property applies when you set CoefficientsSource to 'Property'.

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

Default: [1,0;0,-1]

PaddingMethod

Select one of these methods for padding the boundary of the input image.

  • 'Constant' — Interpret pixels outside the image frame as having a constant value.

  • 'Replicate' — Repeat the value of pixels at the edge of the image.

  • 'Symmetric' — Set the value of the padding pixels to mirror the edge of the image.

  • 'Reflection' — Set the value of the padding pixels to reflect around the pixel at the edge of the image.

  • 'None' — Exclude padding logic. The object does not set the pixels outside the image frame to any particular value. This option reduces the hardware resources that are used by the object and reduces the blanking that is required between frames. However, this option affects the accuracy of the output pixels at the edges of the frame. To maintain pixel stream timing, the output frame is the same size as the input frame. However, to avoid using pixels calculated from undefined padding values, mask off the n/2 pixels around the edge of the frame for downstream operations. n is the size of the operation kernel. For more details, see Increase Throughput with Padding None.

For more information about these methods, see Edge Padding.

Default: 'Constant'

PaddingValue

Constant value used to pad the boundary of the input image. This property applies when you set PaddingMethod to 'Constant'. The object casts this value to the same data type as the input pixel.

Default: 0

LineBufferSize

Size of line memory buffer, specified as a positive integer. Choose a power of two that accommodates the number of active pixels in a horizontal line. If you specify a value that is not a power of two, the buffer uses the next largest power of two.

Choose a power of two that accommodates the number of active pixels in a horizontal line. If you specify a value that is not a power of two, the object uses the next largest power of two. The object allocates (coefficient rows – 1)-by-LineBufferSize memory locations to store the pixels.

Default: 2048

CoefficientsDataType

Select the method for determining the data type of the filter coefficients. This property applies when you set CoefficientsSource to 'Property'.

  • 'Same as first input'' (default) — Sets the data type of the coefficients to match the data type of the pixelIn argument of the step method.

  • 'custom' — Sets the data type of the coefficients to match the data type defined in the CustomCoefficientsDataType property.

When converting the coefficients to the specified data type, the object rounds to the nearest representable value and saturates on overflow.

CustomCoefficientsDataType

Data type for the filter coefficients, specified as numerictype(signed,WL,FL), where WL is the word length and FL is the fraction length in bits. This property applies when you set CoefficientsDataType to 'custom'.

Default: numerictype(true,16,15)

OutputDataType

Select the method for determining the data type of the output pixels.

  • 'Same as first input' (default) — Sets the data type of the output pixels to match the data type of the pixelIn argument of the step method.

  • 'full precision' — Computes internal and output data types using full precision rules. These rules provide accurate fixed-point numerics and prevent quantization within the object. Bits are added, as needed, to prevent rounding and overflow.

  • 'custom' — Sets the data type of the output pixels to match the data type you define in the CustomOutputDataType property.

CustomOutputDataType

Data type for the output pixels, specified as numerictype(signed,WL,FL), where WL is the word length and FL is the fraction length in bits. This property applies only when you set OutputDataType to custom.

Default: numerictype(true,8,0)

OverflowAction

Overflow action used for fixed-point operations.

The object uses fixed-point arithmetic for internal calculations when the input is any integer or fixed-point data type. This option does not apply when the input data type is single or double.

Default: Wrap

RoundingMethod

Rounding mode used for fixed-point operations.

The object uses fixed-point arithmetic for internal calculations when the input is any integer or fixed-point data type. This option does not apply when the input data type is single or double.

Default: Floor

Methods

step2-D FIR filtering
Common to All System Objects
release

Allow System object property value changes

Examples

collapse all

This example uses:

Open Live Script

This example implements a 2-D blur filter on a thumbnail image.

Load the source image from a file. Select a portion of the image matching the desired test size.

frmOrig = imread('rice.png');
frmActivePixels = 64;
frmActiveLines = 48;
frmInput = frmOrig(1:frmActiveLines,1:frmActivePixels);
figure
imshow(frmInput,'InitialMagnification',300)
title 'Input Image'

Figure contains an axes object. The axes object with title Input Image contains an object of type image.

Create a serializer object and specify the size of the inactive pixel regions.

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

Create a filter object. 

 filt2d = visionhdl.ImageFilter(...
          'Coefficients',ones(2,2)/4,...
          'CoefficientsDataType','Custom',...
          'CustomCoefficientsDataType',numerictype(0,1,2),...
          'PaddingMethod','Symmetric');

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(frmInput);

Prepare to process pixels by preallocating output vectors.

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

For each pixel in the padded frame, compute the filtered value. Monitor the control signals to determine latency of the object. The latency of a filter configuration depends on:

  • The number of active pixels in a line.

  • The size of the filter kernel.

  • Optimization of symmetric or duplicate coefficients.

foundValIn = false;
foundValOut = false;
for p = 1:numPixelsPerFrame  
    if (ctrlIn(p).valid && foundValIn==0)
        foundValIn = p;
    end
    [pixOut(p),ctrlOut(p)] = filt2d(pixIn(p),ctrlIn(p));
    if (ctrlOut(p).valid && foundValOut==0)
        foundValOut = p;
    end
end
sprintf('object latency is %d cycles',foundValOut-foundValIn)
ans = 
'object latency is 101 cycles'

Create a deserializer object with a format matching that of the serializer. 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',frmActivePixels,...
      'ActiveVideoLines',frmActiveLines,...
      'TotalPixelsPerLine',frmActivePixels+10);
[frmOutput,frmValid] = pix2frm(pixOut,ctrlOut);
if frmValid
    figure
    imshow(frmOutput, 'InitialMagnification',300)
    title 'Output Image'
end

Figure contains an axes object. The axes object with title Output Image contains an object of type image.

Algorithms

This object implements the algorithms described on the Image Filter block reference page.

Extended Capabilities

Version History

Introduced in R2015a

See Also

| (Image Processing Toolbox) |