visionhdl.MedianFilter

2-D median filtering

Description

The visionhdl.MedianFilter System object™ performs 2-D median filtering on a pixel stream. The object replaces each pixel value with the median value of the adjacent pixels.

To perform 2-D median filtering on a pixel stream:

1. Create the visionhdl.MedianFilter 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

MF = visionhdl.MedianFilter(Name,Value)

MF = visionhdl.MedianFilter(size,Name,Value)

Description

MF = visionhdl.MedianFilter(Name,Value) returns a median filter System object that performs 2-D median filtering of a pixel stream. Set properties using one or more name-value pairs. Enclose each property name in single quotes.

MF = visionhdl.MedianFilter(size,Name,Value) returns a median filter System object, with the NeighborhoodSize property set to size and additional options specified by one or more Name,Value pair arguments.

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.

NeighborhoodSize — Size of image region used to compute median

'3×3' (default) | '5×5' | '7×7'

Neighborhood size, specified as the dimensions in pixels.

LineBufferSize — Size of line buffer

2048 (default) | integer

Size of the 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.

The object allocates N – 1-by-LineBufferSize memory locations to store the pixels used to compute the median value. N is the number of lines in the square region specified in NeighborhoodSize.

PaddingMethod — Method for padding boundary of input image

'Symmetric' (default) | 'Constant' | 'Replicate' | 'Reflection' | 'None'

Methods for padding the boundary of the input image, specified as one of these values.

• '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. 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 by Omiting Padding.

For more information about these methods, see Edge Padding.

You cannot use a neighborhood size of '7×7' when you set PaddingMethod to 'None'.

PaddingValue — Value used to pad boundary of input image

0 (default) | integer

Value used to pad the boundary of the input image, specified as an integer. The object casts this value to the same data type as the input pixel.

Dependencies

This parameter applies when you set PaddingMethod to 'Constant'.

Usage

Syntax

[pixelout,ctrlout] = MF(pixelin,ctrlin)

Description

[pixelout,ctrlout] = MF(pixelin,ctrlin) returns the filtered pixel value, pixelout, and accompanying control signals, resulting from calculating the median of the neighborhood around each input pixel, pixelin. Before filtering, the object pads the image edges according to the PaddingMethod property.

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. Integer and fixed-point data types larger than 16 bits are not supported.

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

Output Arguments

pixelout — Output pixel stream

scalar

Single image pixel in a pixel stream, returned as a scalar value. The data type of pixelout is the same as the data type of pixelin.

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

ctrlout — Control signals accompanying output pixel stream

pixelcontrol structure

Control signals accompanying the output pixel stream, returned 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

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

Median Filter Pixel Stream

This example implements a 5-by-5 median 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');
frmActiveLines = 48;
frmActivePixels = 64;
frmInput = frmOrig(1:frmActiveLines,1:frmActivePixels);
figure
imshow(frmInput,'InitialMagnification',300)
title 'Input 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 and specify a neighbourhood.

 medianfilt = visionhdl.MedianFilter( ...
          'NeighborhoodSize','5x5');

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 local median. Monitor 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 neighbourhood.

foundValIn = false;
foundValOut = false;
for p = 1:numPixelsPerFrame  
    if (ctrlIn(p).valid && foundValIn==0)
        foundValIn = p;
    end
    [pixOut(p),ctrlOut(p)] = medianfilt(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 177 cycles'

Create a deserializer object with a format that matches the format 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

Algorithms

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

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 Verilog and VHDL 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 R2015a

R2021b: Reflection padding

Pad the edge of a frame by reflecting around the edge-pixel value. This padding method helps reduce edge contrast effects and can improve results for machine learning while maintaining the original frame size.

R2020a: Option to omit padding

You can now configure the object to not add padding around the boundaries of the active frame. This option reduces the hardware resources used by the object and reduces the blanking interval required between frames but affects the accuracy of the output pixels at the edges of the frame. To use this option, set the PaddingMethod property to 'None'.

R2019b: Multipixel streaming

The object now supports multipixel streams. For multipixel streaming, the object supports input and output column vectors of 4 or 8 pixels. The ctrl argument remains scalar, and the control signals in the pixelcontrol structure apply to all pixels in the vector.

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.

R2018b: Improved line buffer

The internal line buffer in this object now handles bursty data, that is, noncontiguous valid signals within a pixel line. This implementation uses fewer hardware resources due to improved padding logic and native support for kernel sizes with an even number of lines. This change affects the visionhdl.LineBuffer object and objects that use an internal line buffer.

The latency of the line buffer is now reduced by a few cycles for some configurations. You might need to rebalance parallel path delays in your designs. A best practice is to synchronize parallel paths in your designs by using the pixel stream control signals rather than by inserting a specific number of delays.