Filter Convolution#

Filters an image with a 2D convolution kernel.

Description

This function applies a filter convolution to the source image with the specified kernel window K[k,l].

\[pDst[i,j] = \sum_{k,l=0}^{k_w,k_h}src[i-xAnchor+k,j-yAnchor+l]*K[k,l]\]
\[j \in \{0, 1, ..., roiSize.width\}\]
\[i \in \{0, 1, ..., roiSize.height\}\]

where k_w = rowKernelSize, k_h = columnKernelSize, xAnchor = (rowKernelSize-1)/2, and yAnchor = (columnKernelSize-1)/2.

Algorithm parameters are set through the filter_convolution_spec class. The type of the image border is determined by the value of the border parameter. This function can operate with an ROI (see Image Regions of Interest).

Headers

oneapi/ipl/filter/filter_convolution.hpp

Syntax

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

Convolution 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 layouts (only for DataT = std::uint8_t):

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.
template<typename ComputeT = float>
class filter_convolution_spec#

Convolution filter parameters.

Template Parameters:

ComputeT – the type for computations

Public Functions

filter_convolution_spec(const filter_convolution_spec &other)#

Conversion constructor for filter convolution specification.

Parameters:

other – the other filter convolution specification

explicit filter_convolution_spec(const sycl::range<2> &window, ComputeT *kernel_ptr, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Construct convolution spec with given window, kernel, border type and crop flag.

Parameters:

  • window – window

  • kernel_ptr – pointer to kernel

  • border – border type

  • crop – crop flag

const sycl::range<2> get_window() const noexcept#

Returns the window of filter convolution.

Returns:

the window of filter convolution

const sycl::buffer<ComputeT, 2> &get_kernel() const noexcept#

Returns the kernel of filter convolution.

Returns:

the kernel of filter convolution

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 one of the pitch values is not divisible by the size of the component data type in bytes.

invalid_argument exception

Indicates an error when kernel size is equal to zero.

unimplemented exception

Indicates an error when border type is not supported.

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

// Create queue
sycl::queue queue;
// Create allocator
oneapi::ipl::shared_usm_allocator_t allocator{ queue };

oneapi::ipl::image<oneapi::ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_src_image_data, size };
oneapi::ipl::image<oneapi::ipl::layouts::channel4, std::uint8_t> dst_image{ size, allocator };

// Configure spec to perform a filter convolution with the given 3 by 4 kernel
std::vector<float> kernel{ 0.29900f, 0.58700f, 0.11400f, 0.000f,
                           0.16874f,  -0.33126f, 0.50000f, 128.0f,
                           0.50000f, -0.41869f, -0.08131f, 128.0f };

// Create convolution filter arguments
const oneapi::ipl::filter_convolution_spec<float> spec{ { 3, 4 }, kernel.data() };

// Apply convolution filter to whole image
auto event = oneapi::ipl::filter_convolution(queue, src_image, dst_image, spec);

(void)filter_convolution(queue, src_image, dst_image, spec);