# visionhdl.BilateralFilter

Perform 2-D filtering of a pixel stream

## Description

The `visionhdl.BilateralFilter`

object filters images while preserving
edges. Some applications of bilateral filtering are denoising while preserving edges,
separating texture from illumination, and cartooning to enhance edges. The filter replaces
each pixel at the center of a neighborhood by an average that is calculated using spatial and
intensity Gaussian filters. The object determines the filter coefficients from:

Spatial location in the neighborhood (similar to a Gaussian blur filter)

Intensity difference from the neighborhood center value

The object provides two standard deviation parameters for independent control of the spatial and intensity coefficients.

To perform bilateral filtering of a pixel stream:

Create the

`visionhdl.BilateralFilter`

object 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

### Description

`filt2d = visionhdl.BilateralFilter(`

returns a bilateral filter System object™. Set properties using name-value pairs. Enclose each property name in single
quotes. `Name`

,`Value`

)

For example:

filt2d = visionhdl.BilateralFilter('CoefficientsDataType','Custom',... 'CustomCoefficientsDataType',numerictype(0,18,17))

## 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 to average

`'3×3'`

(default) | `'5×5'`

| `'7×7'`

| `'9×9'`

| `'11×11'`

| `'13×13'`

| `'15×15'`

Size of the image region used to compute the average, specified as an
*N*-by-*N* pixel square.

`SpatialStdDev`

— Spatial standard deviation target

`0.5`

(default) | positive real number

Spatial standard deviation target used to compute coefficients for the spatial Gaussian filter, specified as a positive real number. This parameter has no limits, but recommended values are from 0.1 to 10. At the high end, the distribution becomes flat and the coefficients are small. At the low end, the distribution peaks in the center and has small coefficients in the rest of the neighborhood. These boundary values also depend on the neighborhood size and the data type used for the coefficients.

`IntensityStdDev`

— Intensity standard deviation target

`0.5`

(default) | positive real number

Intensity standard deviation target used to compute coefficients for the intensity Gaussian filter, specified as a positive real number. This parameter has no limits, but recommended values are from 0.1 to 10. At the high end, the distribution becomes flat and the coefficients are small. At the low end, the distribution peaks in the center and has small coefficients in the rest of the neighborhood. These boundary values also depend on the neighborhood size and the data type used for the coefficients.

When the intensity standard deviation is large, the bilateral filter acts more like a Gaussian blur filter, because the intensity Gaussian has a lower peak. Conversely, when the intensity standard deviation is smaller, edges in the intensity are preserved or enhanced.

`PaddingMethod`

— Method for padding boundary of input image

`'Constant'`

(default) | `'Symmetric'`

| `'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 Omitting Padding.

For more information about these methods, see Edge Padding.

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

.

`LineBufferSize`

— Size of line memory buffer

`2048`

(default) | positive 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.

`RoundingMethod`

— Rounding mode for fixed-point operations

`'Floor'`

(default) | `'Ceiling'`

| `'Convergent'`

| `'Nearest'`

| `'Round'`

| `'Zero'`

When the input is any integer or fixed-point data type, the algorithm uses fixed-point
arithmetic for internal calculations. This property does not apply when the input data
type is `single`

or `double`

.

`OverflowAction`

— Overflow mode used for fixed-point operations

`'Saturate'`

(default) | `'Wrap'`

Overflow mode used for fixed-point operations. When the input is any integer or
fixed-point data type, the algorithm uses fixed-point arithmetic for internal
calculations. This option does not apply when the input data type is
`single`

or `double`

.

`CoefficientsDataType`

— Method to determine data type of filter coefficients

`'Same as first input'`

(default) | `'Custom'`

Method for determining the data type of the filter coefficients. The coefficients usually require a data type with more precision than the input data type.

`'Custom'`

— Sets the data type of the coefficients to match the data type defined in the`CustomCoefficientsDataType`

property.`'Same as first input'`

' — Sets the data type of the coefficients to match the data type of the`pixelin`

argument.

`CustomCoefficientsDataType`

— Data type for the filter coefficients

`numerictype(0,16,15)`

(default) | `numerictype(0,WL,FL)`

Data type for the filter coefficients, specified as
`numerictype(0,WL,FL)`

, where *WL* is the word
length and *FL* is the fraction length in bits.

Specify an unsigned data type that can represent values less than 1. The
coefficients usually require a data type with more precision than the input data type.
The object calculates the coefficients based on the neighborhood size and the values of
`IntensityStdDev`

and `SpatialStdDev`

. Larger
neighborhoods spread the Gaussian function such that each coefficient value is smaller.
A larger standard deviation flattens the Gaussian so that the coefficients are more
uniform in nature, and a smaller standard deviation produces a peaked response.

**Note**

If you try a data type and after quantization, more than half of the coefficients become zero, the object issues a warning. If all the coefficients are zero after quantization, the object issues an error. These messages mean that the object was unable to express the requested filter by using the data type specified. To avoid this issue, choose a higher-precision coefficient data type or adjust the standard deviation parameters.

#### Dependencies

This property applies when you set `CoefficientsDataType`

to
`'Custom'`

.

`OutputDataType`

— Method to determine data type of output pixels

`'Same as first input'`

(default) | `'Custom'`

Method to determine data type of output pixels.

`'Same as first input'`

' — Sets the data type of the output pixels to match the data type of`pixelin`

.`'Custom'`

— Sets the data type of the output pixels to match the data type defined in the`CustomOutputDataType`

property.

`CustomOutputDataType`

— Data type for the output pixels

`numerictype(1,16,15)`

(default) | `numerictype(S,WL,FL)`

Data type for the output pixels, specified as
`numerictype(S,WL,FL)`

, where *S* is
`1`

(`true`

) for signed and
`0`

(`false`

) for unsigned,*WL* is the word
length, and *FL* is the fraction length in bits. The filtered pixel
values are cast to this data type.

#### Dependencies

This property applies when you set `OutputDataType`

to
`'Custom'`

.

## Usage

### Description

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 representing intensity. 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`

| `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 representing intensity. 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`

| `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)

## Examples

### Create Bilateral Filter for HDL Generation

Load input image and create serializer and deserializer objects.

frmOrig = imread('rice.png'); frmActivePixels = 48; frmActiveLines = 32; frmIn = frmOrig(1:frmActiveLines,1:frmActivePixels); figure imshow(frmIn,'InitialMagnification',300) title 'Input Image' frm2pix = visionhdl.FrameToPixels(... 'NumComponents',1,... 'VideoFormat','custom',... 'ActivePixelsPerLine',frmActivePixels,... 'ActiveVideoLines',frmActiveLines,... 'TotalPixelsPerLine',frmActivePixels+10,... 'TotalVideoLines',frmActiveLines+10,... 'StartingActiveLine',6,... 'FrontPorch',5); [~,~,numPixPerFrm] = getparamfromfrm2pix(frm2pix); pix2frm = visionhdl.PixelsToFrame(... 'NumComponents',1,... 'VideoFormat','custom',... 'ActivePixelsPerLine',frmActivePixels,... 'ActiveVideoLines',frmActiveLines,... 'TotalPixelsPerLine',frmActivePixels+10);

Write a function that creates and calls the System object™. You can generate HDL from this function.

function [pixOut,ctrlOut] = BilatFilt(pixIn,ctrlIn) %bilatFilt % Filters one pixel according to the default spatial and intensity standard % deviation, 0.5. % pixIn and pixOut are scalar intensity values. % ctrlIn and ctrlOut are structures that contain control signals associated % with the pixel. % You can generate HDL code from this function. persistent filt2d; if isempty(filt2d) filt2d = visionhdl.BilateralFilter(... 'CoefficientsDataType','Custom',... 'CustomCoefficientsDataType',numerictype(0,18,17)); end [pixOut,ctrlOut] = filt2d(pixIn,ctrlIn); end

Filter the image by calling the function for each pixel.

pixOutVec = zeros(numPixPerFrm,1,'uint8'); ctrlOutVec = repmat(pixelcontrolstruct,numPixPerFrm,1); [pixInVec,ctrlInVec] = frm2pix(frmIn); for p = 1:numPixPerFrm [pixOutVec(p),ctrlOutVec(p)] = BilatFilt(pixInVec(p),ctrlInVec(p)); end [frmOut,frmValid] = pix2frm(pixOutVec,ctrlOutVec); if frmValid figure; imshow(frmOut,'InitialMagnification',300) title 'Output Image' end

## 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 VHDL, Verilog and SystemVerilog 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 R2017b**

### R2022a: Multipixel streaming

The object now supports multipixel streams. For multipixel streaming, the object
supports input and output column vectors of 2, 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.

### 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'`

.

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

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)