Color Twist#

Converts an image using a color-twist matrix.

Description

This function applies a color-twist matrix to the source image and use values of all color channels of a source pixel to compute the resultant destination channel value. This function obtains the destination channel value as the result of multiplying the corresponding row of the color-twist matrix by the vector of source pixel channel values.

For example, if (r,g,b) is a source pixel, then this function computes the destination pixel values (R,G,B) using formulae:

R = t₁₁ * r + t₁₂ * g + t₁₃ * b + t₁₄

G = t₂₁ * r + t₂₂ * g + t₂₃ * b + t₂₄

B = t₃₁ * r + t₃₂ * g + t₃₃ * b + t₃₄

where

\[\begin{split}T=\begin{bmatrix} t_{11} & t_{12} & t_{13} & t_{14} \\ t_{21} & t_{22} & t_{23} & t_{24} \\ t_{31} & t_{32} & t_{33} & t_{34} \end{bmatrix}\end{split}\]

is the color-twist matrix. This function supports color-twist matrices of size 3x4, or 4x4 with single-precision or double-precision floating-point elements. The matrix elements are specific for each particular type of color conversion.

Algorithm parameters shall be set through the color_twist_spec class.

When the row size of twist matrix is 3, the number of channels shall be 3 or 4, this type of alpha handling shall correspond to the ignore_alpha value in the alpha_handling_types enumerator. The computation ignores alpha channel in source image pixels and its values remains unchanged in destination image pixels.
When the row size of twist matrix is 4, the number of channels shall only be 4, this type of alpha handling shall correspond to the process_alpha value in the alpha_handling_types enumerator. The computation processes alpha channel in source image pixels but its values remains unchanged in destination image pixels.

This function can operate with ROI (see Image Regions of Interest).

This function does not support in-place operations currently.

Headers

oneapi/ipl/convert/color_twist.hpp

Syntax

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

Color Twist.

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
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 combinations for Color-twist matrix sizes/Layouts:

Color-twist matrix sizes/Layouts	plane	channel3	channel4	plane3
3x4	✗	✓	✓	✓
4x4	✗	✗	✓	✗

Parameters

color-twist matrix support	Input of color-twist matrix should shall be a pointer to the first element of the two-dimensional array.
enumerated attribute `alpha_handling_types` support	When the row size of twist matrix is 3, alpha channel in source image pixels shall be ignored and `alpha_handling_types` shall be `ignore_alpha`. When the row size of twist matrix is 4, alpha channel in source image pixels shall be processed and `alpha_handling_types` shall be `process_alpha`.

template<typename ComputeT = float> class color_twist_spec#

Color Twist parameters.

Public Functions

constexpr color_twist_spec(const ComputeT *p_twist, const alpha_handling_types alpha_handling_type)#

Construct Color Twist specification.

Parameters:

p_twist – twist matrix pointer
alpha_handling_type – alpha handling type

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

Returns the twist matrix sycl buffer.

Returns:: the twist matrix sycl buffer

constexpr alpha_handling_types get_alpha_handling_type() const noexcept#

Returns the alpha handling type how to deal with Alpha value source image pixels.

Returns:: alpha handling type

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 image data type is not supported.
compile-time compute data type check	Indicates an error when compute data type is not supported.
`invalid_argument`	Indicates an error when 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 size of component data type in bytes.
`invalid_argument` exception	Indicates an error when `alpha_handling_types` and the image layouts are incorrectly configured.

The code example below demonstrates how oneapi::ipl::color_twist shall be 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_src_image_data, image_size, allocator };
// Destination 4-channel image data
ipl::image<ipl::layouts::channel4, std::uint8_t> dst_image{ queue, p_dst_image_data, image_size, allocator };

// Create a 3x4 color twist matrix
constexpr ipl::alpha_handling_types alpha_handling_type{ ipl::alpha_handling_types::ignore_alpha };

const float twist[3][4] = { { 0.29900f, 0.58700f, 0.11400f, 0.000f },
                            { -0.16874f, -0.33126f, 0.50000f, 128.0f },
                            { 0.50000f, -0.41869f, -0.08131f, 128.0f } };

// Color twist spec with twist matrix
const ipl::color_twist_spec spec{ &twist[0][0], alpha_handling_type };

// Apply color_twist to the 4-channel image with uint8_t data type
auto event = ipl::color_twist(queue, src_image, dst_image, spec);