Box Filter

Blurs an image using a simple box filter

Description

This function computes each pixel in the destination image as the average of all pixels from the source image in the rectangular neighborhood of window size anchored at that pixel. This has a smoothing or blurring effect on the input image. Algorithm parameters are set through the filter_box_spec class. The values of border pixels are determined by the border type. The formula below describes the window:

\[\begin{split}K = \alpha \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \vdots & \vdots & \vdots & \ddots & \vdots & \vdots \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}\end{split}\]

\[\alpha = \dfrac{1}{ksize.width * ksize.height}\]

where

• ksize.width and ksize.height are the width and height of the box filter window, respectively

• K is window size

The window is rectangular and the coordinates of the anchor are computed by: anchor.x = (window.width-1)/2 and anchor.y = (window.height-1)/2, where window.width and window.height are the width and height of the box filter window, respectively. This function can operate with an ROI (see Image Regions of Interest).

Headers

oneapi/ipl/filter/filter_box.hpp

Syntax

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

Box 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):

sub420i	sub420
✗	✗

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.

class filter_box_spec

Box filter parameters.

Public Functions

filter_box_spec(const filter_box_spec &other)

Conversion constructor for Box filter specification.

Parameters:

other – the other Box filter specification

explicit filter_box_spec(const sycl::range<2> &window, border_types border = border_types::repl, crop_types crop = crop_types::on)

Construct Box filter spec from given window, border type and crop flag.

Parameters:

• window – window

• border – border type

• crop – crop flag

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

Returns the window of Box filter.

Returns:

the window of Box filter

Errors

compile-time layout check	Indicates an error when image 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	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 the window size is invalid.
unimplemented exception	Indicates an error when border type is not supported.

The code example below demonstrates how oneapi::ipl::filter_box 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 };

// Create Filter Box arguments (window = { 7, 5 })
const ipl::filter_box_spec spec{ { 7, 5 } };

auto event = ipl::filter_box(queue, src_image, dst_image, spec);