Warp Nearest#

The Warp Nearest function performs a geometric warp of an image by resampling the data with a recomputed coordinate system. The resampling utilizes nearest neighbor interpolation. The function provides access to both perspective and strictly affine transformations.

Description

The function performs either a perspective or affine transform with nearest neighbor resampling. The perspective coordinate transform from \((x, y)\) to \((x', y')\) is defined as:

\[\begin{split}\begin{array}{c} x' = \frac{c_{00} \cdot x + c_{01} \cdot y + c_{02}}{c_{20} \cdot x + c_{21} \cdot y + c_{22}} \\ y' = \frac{c_{10} \cdot x + c_{11} \cdot y + c_{12}}{c_{20} \cdot x + c_{21} \cdot y + c_{22}} \end{array}\end{split}\]

In the case of an affine transformation, the function assumes that \(c_{20} = 0, c_{21} = 0\), and \(c_{22} = 1\) so the formulas is simplified to:

\[\begin{split}\begin{array}{c} x' = c_{00} \cdot x + c_{01} \cdot y + c_{02} \\ y' = c_{10} \cdot x + c_{11} \cdot y + c_{12} \end{array}\end{split}\]

where

\(x', y'\) are the pixel coordinates in the transformed image
\(x, y\) are the pixel coordinates of the input image
\(c_{ij}\) are the transform coefficients passed to the coeffs array during initialization

The function supports edge smoothing (see Edge Smoothing).

Specify a transformation to warp nearest with the warp_nearest_spec class; constructors build arguments that strictly define perspective or affine transforms. The constructors derive transforms from source and destination quadrilaterals/triangles or may accept coefficients directly.

Headers

oneapi/ipl/transform/warp_nearest.hpp

Syntax

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

Warp Nearest.

Template Parameters:

ComputeT – type to perform calculations
SrcImageT – Source image type
DstImageT – Destination image type

Parameters:

queue – [in] SYCL queue
src – [in] source image
dst – [out] destination image
spec – [in] algorithmic specification
border_val – [in] border value
dependencies – [in] other events dependencies

Returns:

SYCL event, that represents a status of an operation it associated with

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 DataT = std::uint8_t):

sub420	sub420i
✗	✗

Parameters

direction	Warp Perspective direction. Possible values are: `forward` - Forward Warp Perspective. `backward` - Backward Warp Perspective.
infinite ROI	Infinite ROI option. Possible values are: `true` - Pixels that are outside the source image boundaries are set according to the specified border type. `false` - Operations take place only inside the source image.
edge smoothing	Type of edge smoothing. Possible values are: `on` - Edge smoothing is applied. Supported only for `transp` border type. `off` - Edge smoothing is not applied.
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. `transp` - Pixels that require outer source pixels for calculations are not processed.

template<typename ComputeT> class warp_nearest_spec#

Warp Nearest Specification.

Template Parameters:: ComputeT – the type for computations

Public Functions

explicit warp_nearest_spec(const roi_rect &src_roi, const std::array<sycl::id<2>, 4> &dst_quad, directions direction = directions::forward, bool infinite_src_roi = false, smooth_types smooth_edge = smooth_types::off, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Perspective Transform constructor.

Parameters:

src_roi – The source region of interest (ROI)
dst_quad – The destination quadrangle
direction – The direction of the transformation, defaults to forward
infinite_src_roi – Whether the source region is infinite, defaults to false
smooth_edge – The type of smooth edge to use, defaults to smooth_types::off
border – The border type to use, defaults to border_types::repl
crop – The crop flag, defaults to crop_types::on

explicit warp_nearest_spec(const roi_rect &src_roi, const std::array<sycl::id<2>, 3> &dst_tri, directions direction = directions::forward, bool infinite_src_roi = false, smooth_types smooth_edge = smooth_types::off, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Affine Transform constructor.

Parameters:

src_roi – Source rectangle to transform.
dst_tri – Array of 3 vertices for the destination triangle.
direction – The direction of the transformation, defaults to forward
infinite_src_roi – Whether the source region is infinite, defaults to false
smooth_edge – The type of smooth edge to use, defaults to smooth_types::off
border – The border type to use, defaults to border_types::repl
crop – The crop flag, defaults to crop_types::on

explicit warp_nearest_spec(const std::array<ComputeT, 6> &coefficients, directions direction = directions::forward, bool infinite_src_roi = false, smooth_types smooth_edge = smooth_types::off, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Affine Transform constructor with coefficients.

Parameters:

coefficients – Array of 6 coefficients for affine transform.
direction – The direction of the transformation, defaults to forward
infinite_src_roi – Whether the source region is infinite, defaults to false
smooth_edge – The type of smooth edge to use, defaults to smooth_types::off
border – The border type to use, defaults to border_types::repl
crop – The crop flag, defaults to crop_types::on

explicit warp_nearest_spec(const std::array<ComputeT, 9> &coefficients, directions direction = directions::forward, bool infinite_src_roi = false, smooth_types smooth_edge = smooth_types::off, border_types border = border_types::repl, crop_types crop = crop_types::on)#

Perspective Transform constructor with coefficients.

Parameters:

coefficients – Array of 9 coefficients for perspective transform.
direction – The direction of the transformation, defaults to forward
infinite_src_roi – Whether the source region is infinite, defaults to false
smooth_edge – The type of smooth edge to use, defaults to smooth_types::off
border – The border type to use, defaults to border_types::repl
crop – The crop flag, defaults to crop_types::on

const std::array<sycl::id<2>, 4> get_perspective_quad(const roi_rect &src_rect) const#

Computes the destination quadrangle based on source ROI and perspective coefficients.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The destination quadrangle as an array of sycl::id<2>.

const std::array<sycl::id<2>, 4> get_perspective_quad(const roi_rect &src_rect)#

Computes the destination quadrangle based on source ROI and perspective coefficients.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The destination quadrangle as an array of sycl::id<2>.

const roi_rect get_perspective_bound(const roi_rect &src_rect)#

Computes the bounding rectangle for a perspective transform.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The ROI around the quadrangle, to which the source ROI is mapped by the perspective transform.

const std::array<sycl::id<2>, 4> get_affine_quad(const roi_rect &src_rect) const#

Computes the destination quadrangle for an affine transform.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The destination quadrangle as an array of sycl::id<2>.

const std::array<sycl::id<2>, 4> get_affine_quad(const roi_rect &src_rect)#

Computes the destination quadrangle for an affine transform.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The destination quadrangle as an array of sycl::id<2>.

const roi_rect get_affine_bound(const roi_rect &src_rect)#

Computes the bounding rectangle for an affine transform.

Parameters:: src_rect – The source rectangle to transform.
Returns:: The ROI around the quadrangle, to which the source ROI is mapped by the affine transform.

const sycl::buffer<ComputeT, 1> &get_coefficients() const noexcept#

Retrieves the buffer containing transformation coefficients.

Returns:: A SYCL buffer containing the coefficients.

directions get_direction() const#

Retrieves the direction of the transformation.

Returns:: The direction of the transformation as a member of the ‘directions’ enum.

bool is_infinite_src_roi() const#

Checks whether the source ROI is infinite.

Returns:: ‘true’ if the source ROI is considered infinite, ‘false’ otherwise.

smooth_types is_smooth_edge() const#

Retrieves the type of smoothing applied to edges.

Returns:: The type of edge smoothing as a member of the ‘smooth_types’ enum.

warp_transform_types get_transform_type() const#

Retrieves the type of transformation being applied.

Returns:: The type of transformation as a member of the ‘transform_types’ enum.

Errors

compile-time layout check	Indicates an error when image layout is not supported.
compile-time data type check	Indicates an error when image data type is not supported.
compile-time compute data type check	Indicates an error when compute data type is not supported.
`invalid_argument` exception	Indicates an error when one of the pitch values is not divisible by size of component data type in bytes.
`invalid_argument` exception	Indicates an error when warp coefficients matrix is invalid.
`unimplemented` exception	Indicates an error when border type is not supported.
`unimplemented` exception	Indicates an error when border type and crop combination is not supported.
`unimplemented` exception	Indicates an error when border type and smooth edge option combination is not supported.

The code example below demonstrates how oneapi::ipl::warp_nearest shall be called:

using namespace oneapi;

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

// Image representing source RGBA image
ipl::image<ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// Destination image with Warp Perspective Nearest result
ipl::image<ipl::layouts::channel4, std::uint8_t> dst_image{ image_size, allocator };

// Define a transform from the entire source image ROI
const roi_rect src_rect{
    sycl::id<2>{ static_cast<std::size_t>(0), static_cast<std::size_t>(0) },
    sycl::range<2>{ static_cast<std::size_t>(width), static_cast<std::size_t>(height) }
};

// Transform the source image to a quadrilateral
std::array<sycl::id<2>, 4> dst_quad{
    sycl::id<2>( 0, src_size[1] ),
    sycl::id<2>( (src_size[0] - 1) / 2, (src_size[1] - 1) ),
    sycl::id<2>( src_size[0] - 1, (src_size[1] - 1) / 2 ),
    sycl::id<2>( (src_size[0] - 1) / 2, 0 )
};

// Define a perspective transform by providing a destination quadrangle. A quadrangle implies a
// perspective transform while a destination triangle (parallelogram) instead creates an affine
// transform. This invokes a perspective-optimized warp function.
const warp_nearest_spec<float> spec{ src_rect, dst_quad };
auto event = warp_nearest(queue, src_image, dst_image, spec);