Bilateral Filter#

Filters an image using a bilateral filter.

Description

This function applies a bilateral filter to the source image with the specified kernel radius. Algorithm parameters are set through the bilateral_spec class. The values of border pixels are determined by the border type.

The coefficients of the bilateral filter kernel depend on their positions in the kernel and on the intensity value of the source image pixels lying in the kernel. The value of the output pixel intensity ID is computed by the following formula:

\[I_{D}(i, j) = \dfrac{\sum\limits_{k, l} I(k, l) w(i, j, k, l) }{\sum\limits_{k, l} w(i, j, k, l)}\]

The formula below describes the algorithm of the compute kernel.

\[w(i, j, k, l) = \exp \left( - \dfrac{(i - k)^{2} + (j - l)^{2} }{2 \sigma_{d}^{2}} - \dfrac{norm(I(i, j) - I(k, l))^{2}}{2 \sigma_{i}^{2}} \right)\]

where

  • σd and σi are Gaussian smoothing parameters for distance and intensity, respectively

  • I(i, j) and I(k, l) are the intensity of pixels (i,j) and (k,l) respectively.

  • norm(x) is the vector norm which can be L1 or L2. Currently, only the L1 norm is supported.

  • l,k are indices of the pixels under the window computing pixel (i, j).

Headers

oneapi/ipl/filter/bilateral.hpp

Syntax

template<typename ComputeT = float, typename SrcImageT, typename DstImageT>
sycl::event oneapi::ipl::bilateral(sycl::queue &queue, SrcImageT &src, DstImageT &dst, const bilateral_spec<ComputeT> &spec, const typename SrcImageT::pixel_t &border_val = {}, const std::vector<sycl::event> &dependencies = {})#

Bilateral filter.

Template Parameters:

  • ComputeT – type to perform calculations

  • SrcImageT – Source image type

  • DstImageT – Destination image type

Parameters:

  • queue – SYCL queue

  • src – source image

  • dst – destination image

  • spec – algorithmic spec

  • border_val – border value

  • dependencies – dependencies

Returns:

SYCL event

Supported values for ComputeT:

float

double

half

✓

✓

✗

Supported combinations for DataT/Formats:

DataT/Formats

plane

channel3

channel4

plane3

std::uint8_t

✓

✓

✓

✓

std::int8_t

✓

✓

✓

✓

std::uint16_t

✓

✓

✓

✓

std::int16_t

✓

✓

✓

✓

std::uint32_t

✓

✓

✓

✓

std::int32_t

✓

✓

✓

✓

float

✓

✓

✓

✓

double

✓

✓

✓

✓

Supported values for subsampled layouts (only for DataT = std::uint8_t):

nv12

i420

✗

✗

Parameters

border type support

Type of border. Possible values are:

const_val - Values of all border pixels are set to constant.

repl - Border is replicated from the edge pixels.
template<typename ComputeT = float>
class bilateral_spec#

Bilateral filter parameters.

Template Parameters:

ComputeT – the type for computing

Public Functions

explicit bilateral_spec(std::size_t radius, ComputeT sigma_int, ComputeT sigma_dist, border_types border = border_types::repl, crop_types crop = crop_types::on, norm_types norm = norm_types::l1)#

Construct Bilateral spec with given radius, sigmas, border type, crop flag, normalization type.

Parameters:

  • radius – kernel radius

  • sigma_int – intensity sigma parameter of Bilateral filter

  • sigma_dist – distance sigma parameter of Bilateral filter

  • border – border type

  • crop – crop flag

  • norm – norm to compute distance

template<typename OtherComputeT>
bilateral_spec(const bilateral_spec<OtherComputeT> &other)#

Conversion constructor for bilateral specification.

Template Parameters:

OtherComputeT – the other type for computations

Parameters:

other – the other bilateral specification

std::size_t get_radius() const noexcept#

Returns the radius of Bilateral filter.

Returns:

the radius of Bilateral filter

const sigma_t<ComputeT> &get_sigma() const noexcept#

Returns 2-component sigma of Bilateral filter.

Returns:

the 2-component sigma of Bilateral filter

norm_types get_norm() const noexcept#

Returns the norm of Bilateral filter.

Returns:

the norm of Bilateral filter

Errors

compile-time format check

Indicates an error when image format is not supported.

compile-time data type check

Indicates an error when the image data type is not supported.

compile-time compute data type check

Indicates an error when the compute data type is not supported.

invalid_argument exception

Indicates an error when the ROI sizes of the source image and the destination image are not equal.

invalid_argument exception

Indicates an error when the zero radius or non-positive sigma is provided.

invalid_argument exception

Indicates an error when one of the pitch values is not divisible by the size of the component data type in bytes.

unimplemented exception

Indicates an error when border type is not supported.

The code example below demonstrates how oneapi::ipl::bilateral is called:

using namespace oneapi;

sycl::queue                 queue;
ipl::shared_usm_allocator_t allocator{ queue };
const sycl::range<2>        image_size{ height, width };

// Source 4-channel image data
ipl::image<ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// Destination 4-channel image data
ipl::image<ipl::layouts::channel4, std::uint8_t> dst_image{ image_size, allocator };

// Bilateral arguments: kernel radius = 7, intensity sigma 75, distance sigma 25
const ipl::bilateral_spec<float> spec{ 7, 75., 25. };

// Compute bilateral filter
auto event = ipl::bilateral(queue, src_image, dst_image, spec);