Gaussian Filter#

Filters an image using a Gaussian filter.

Description

This function applies a Gaussian filter to the source image with the specified kernel radius. Algorithm parameters are set through the gaussian_spec class. The values of border pixels are determined by the border type. This function can operate with image ROIs (see Image Regions of Interest). The formula below describes the algorithm of the compute kernel.

\[G(i, j) = \exp \left\{ - \left( \dfrac{(K / 2 - i)^{2}}{2 \sigma_{x}^{2}} + \dfrac{(K / 2 - j)^{2}}{2 \sigma_{y}^{2}} \right) \right\}, i, j = 0 \ldots K\]

where

  • K is the kernel size, K/2 is the kernel radius

  • sigmax and sigmay are standard deviations of the Gaussian distribution in X and Y directions, respectively

  • Gi,j are Gaussian kernel values

Headers

oneapi/ipl/filter/gaussian.hpp

Syntax

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

Gaussian 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/Layouts:

DataT/Layouts

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 layout (only for std::uint8_t data type):

sub420

sub420i

✗

✗

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.

mirror - Border is mirrored from the edge pixels.
template<typename ComputeT = float>
class gaussian_spec#

Gaussian filter parameters.

Template Parameters:

ComputeT – the type for computations

Public Functions

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

Conversion constructor for Gaussian specification.

Template Parameters:

OtherComputeT – the other type for computations

Parameters:

other – the other Gaussian specification

explicit gaussian_spec(std::size_t radius, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Construct Gaussian spec by OpenCV formula and given border type and crop flag.

Parameters:

  • radius – kernel radius

  • border – border type

  • crop – crop flag

template<typename OtherComputeT>
explicit gaussian_spec(std::size_t radius, OtherComputeT sigma, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Construct Gaussian spec with given radius, sigma (same for both X and Y directions), border type and crop flag.

Template Parameters:

OtherComputeT – other type for computations

Parameters:

  • radius – kernel radius

  • sigma – sigma parameter of Gaussian filter

  • border – border type

  • crop – crop flag

template<typename OtherComputeT>
explicit gaussian_spec(std::size_t radius, const sigma_t<OtherComputeT> &sigma, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Construct Gaussian spec with given radius, 2-component sigma, border type and crop flag.

Template Parameters:

OtherComputeT – other type for computations

Parameters:

  • radius – kernel radius

  • sigma – 2-component sigma parameter of Gaussian filter

  • border – border type

  • crop – crop flag

std::size_t get_radius() const noexcept#

Returns the radius of Gaussian filter.

Returns:

the radius of Gaussian filter

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

Returns 2-component sigma of Gaussian filter.

Returns:

the 2-component sigma of Gaussian filter

Errors

compile-time memory layout check

Indicates an error when image memory layout 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::gaussian 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 };

const ipl::gaussian_spec spec{ 2 };

// Gaussian filter with kernel radius = 2 and sigma calculated
auto event = ipl::gaussian(queue, src_image, dst_image, spec);