Dense odd-sized 2-D convolution kernel. More...

#include <ca-kernels.H>

Inheritance diagram for Aleph::CA::Kernel2D< T, Rows, Cols >:

Collaboration diagram for Aleph::CA::Kernel2D< T, Rows, Cols >:

Public Types
using	value_type = T
	Numeric weight type.

Public Member Functions
constexpr	Kernel2D ()=default
	Construct a zero kernel.

constexpr	Kernel2D (const std::array< T, size_v > &weights)
	Construct a kernel from row-major weights.

	Kernel2D (std::initializer_list< T > weights)
	Construct a kernel from a flat initializer list.

	Kernel2D (std::initializer_list< std::initializer_list< T > > rows)
	Construct a kernel from nested row initializer lists.

T	operator() (const std::size_t row, const std::size_t col) const
	Return a weight by matrix position.

T	weight_at_offset (const ca_index_t di, const ca_index_t dj) const
	Return the weight at an offset from the centre.

T	neighbour_weight (const std::size_t k) const
	Return a centre-skipping neighbour weight.

constexpr T	center () const noexcept
	Return the centre weight.

constexpr const std::array< T, size_v > &	weights () const noexcept
	Return the raw row-major weight array.

constexpr T	sum () const noexcept
	Sum every kernel weight.

template<typename State >
T	apply (const State &center_value, Neighbor_View< State > neighbours) const
	Apply the kernel to centre plus neighbour values.

Matrix< int, int, T >	to_matrix () const
	Export the kernel weights as an `Aleph::Matrix`.

Static Public Attributes
static constexpr std::size_t	rows_v = Rows
	Number of rows.

static constexpr std::size_t	cols_v = Cols
	Number of columns.

static constexpr std::size_t	size_v = Rows * Cols
	Total number of weights including the centre.

static constexpr std::size_t	neighbour_count_v = size_v - 1
	Number of neighbour weights excluding the centre.

static constexpr std::size_t	radius_v = Rows / 2
	Chebyshev radius matched by `Moore<2, radius_v>`.

Static Private Member Functions
static constexpr std::size_t	index (const std::size_t row, const std::size_t col) noexcept

Private Attributes
std::array< T, size_v >	weights_ {}

Detailed Description

template<typename T, std::size_t Rows, std::size_t Cols>
class Aleph::CA::Kernel2D< T, Rows, Cols >

Dense odd-sized 2-D convolution kernel.

Kernel coordinates are stored in row-major order. The centre weight is operator()(Rows / 2, Cols / 2). Neighbour weights are exposed through neighbour_weight(k) using the same row-major, centre-skipping order as Moore<2, radius_v>, so a rule can combine this kernel with the neighbour buffer gathered by the standard CA engine without carrying offsets alongside the values.

Template Parameters

T	numeric weight type.
Rows	number of rows; must be odd.
Cols	number of columns; must be odd and equal to Rows for direct use with `Moore<2, radius_v>`.

Definition at line 82 of file ca-kernels.H.

Member Typedef Documentation

◆ value_type

template<typename T , std::size_t Rows, std::size_t Cols>

using Aleph::CA::Kernel2D< T, Rows, Cols >::value_type = T

Numeric weight type.

Definition at line 91 of file ca-kernels.H.

Constructor & Destructor Documentation

◆ Kernel2D() [1/4]

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D ( )

constexprdefault

Construct a zero kernel.

Exceptions

This	function does not throw.

◆ Kernel2D() [2/4]

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D ( const std::array< T, size_v > & weights )

inlineexplicitconstexpr

Construct a kernel from row-major weights.

Parameters

[in] weights flat row-major weight array.

Exceptions

This	function does not throw.

Definition at line 124 of file ca-kernels.H.

◆ Kernel2D() [3/4]

template<typename T , std::size_t Rows, std::size_t Cols>

Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D ( std::initializer_list< T > weights )

inlineexplicit

Construct a kernel from a flat initializer list.

Parameters

[in] weights row-major weights; must contain Rows * Cols entries.

Exceptions

std::length_error if the initializer list has the wrong size.

Definition at line 132 of file ca-kernels.H.

References ah_length_error_if, Aleph::CA::Kernel2D< T, Rows, Cols >::size_v, w, Aleph::CA::Kernel2D< T, Rows, Cols >::weights(), and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ Kernel2D() [4/4]

template<typename T , std::size_t Rows, std::size_t Cols>

Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D ( std::initializer_list< std::initializer_list< T > > rows )

inlineexplicit

Construct a kernel from nested row initializer lists.

Parameters

[in] rows rows of weights; every row must contain Cols entries and the outer list must contain Rows rows.

Exceptions

std::length_error if the shape is not exactly Rows x Cols.

Definition at line 147 of file ca-kernels.H.

References ah_length_error_if, Aleph::CA::Kernel2D< T, Rows, Cols >::index(), r, row, rows, w, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

Member Function Documentation

◆ apply()

template<typename T , std::size_t Rows, std::size_t Cols>

template<typename State >

T Aleph::CA::Kernel2D< T, Rows, Cols >::apply	(	const State &	center_value,
		Neighbor_View< State >	neighbours
	)		const

inline

Apply the kernel to centre plus neighbour values.

Template Parameters

State scalar value type convertible to T.

Parameters

[in]	center_value	value at the centre cell.
[in]	neighbours	neighbour values in `Moore<2, radius_v>` order.

Returns: weighted convolution result in T.

Exceptions

std::length_error if neighbours.size() is not neighbour_count_v.

Definition at line 266 of file ca-kernels.H.

References ah_length_error_if, Aleph::and, Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Kernel2D< T, Rows, Cols >::center(), Aleph::CA::Kernel2D< T, Rows, Cols >::index(), k, Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_count_v, out, r, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ center()

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr T Aleph::CA::Kernel2D< T, Rows, Cols >::center ( ) const

inlineconstexprnoexcept

Return the centre weight.

Returns: operator()(Rows / 2, Cols / 2).

Exceptions

This	function does not throw.

Definition at line 228 of file ca-kernels.H.

References Aleph::CA::Kernel2D< T, Rows, Cols >::index(), and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::apply().

◆ index()

template<typename T , std::size_t Rows, std::size_t Cols>

static constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::index	(	const std::size_t	row,
		const std::size_t	col
	)

inlinestaticconstexprprivatenoexcept

Definition at line 107 of file ca-kernels.H.

References col, and row.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D(), Aleph::CA::Kernel2D< T, Rows, Cols >::apply(), Aleph::CA::Kernel2D< T, Rows, Cols >::center(), Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_weight(), Aleph::CA::Kernel2D< T, Rows, Cols >::operator()(), Aleph::CA::Kernel2D< T, Rows, Cols >::to_matrix(), and Aleph::CA::Kernel2D< T, Rows, Cols >::weight_at_offset().

◆ neighbour_weight()

template<typename T , std::size_t Rows, std::size_t Cols>

T Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_weight ( const std::size_t k ) const

inline

Return a centre-skipping neighbour weight.

The index follows the canonical Moore<2, radius_v> order: row-major over the square stencil, excluding (0, 0).

Parameters

[in] k neighbour index in [0, neighbour_count_v).

Returns: selected neighbour weight.

Exceptions

std::out_of_range if k is out of range.

Definition at line 205 of file ca-kernels.H.

References ah_out_of_range_error_if, Aleph::and, Aleph::CA::Kernel2D< T, Rows, Cols >::index(), k, Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_count_v, out, r, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ operator()()

template<typename T , std::size_t Rows, std::size_t Cols>

T Aleph::CA::Kernel2D< T, Rows, Cols >::operator()	(	const std::size_t	row,
		const std::size_t	col
	)		const

inline

Return a weight by matrix position.

Parameters

[in]	row	row index in `[0, Rows)`.
[in]	col	column index in `[0, Cols)`.

Returns: selected kernel weight.

Exceptions

std::out_of_range if either coordinate is out of range.

Definition at line 171 of file ca-kernels.H.

References ah_out_of_range_error_if, Aleph::blossom_maximum_cardinality_matching(), col, Aleph::CA::Kernel2D< T, Rows, Cols >::index(), row, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ sum()

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr T Aleph::CA::Kernel2D< T, Rows, Cols >::sum ( ) const

inlineconstexprnoexcept

Sum every kernel weight.

Returns: arithmetic sum of all weights.

Exceptions

This	function does not throw.

Definition at line 248 of file ca-kernels.H.

References Aleph::blossom_maximum_cardinality_matching(), w, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ to_matrix()

template<typename T , std::size_t Rows, std::size_t Cols>

Matrix< int, int, T > Aleph::CA::Kernel2D< T, Rows, Cols >::to_matrix ( ) const

inline

Export the kernel weights as an Aleph::Matrix.

The returned sparse matrix uses row domain [0, Rows - 1] and column domain [0, Cols - 1]. Zero weights are omitted by the matrix storage.

Returns: sparse matrix carrying the same weights.

Exceptions

Any	exception thrown by `Matrix` construction or insertion.

Definition at line 296 of file ca-kernels.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Kernel2D< T, Rows, Cols >::index(), r, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ weight_at_offset()

template<typename T , std::size_t Rows, std::size_t Cols>

T Aleph::CA::Kernel2D< T, Rows, Cols >::weight_at_offset	(	const ca_index_t	di,
		const ca_index_t	dj
	)		const

inline

Return the weight at an offset from the centre.

Parameters

[in]	di	signed row offset in `[-radius_v, radius_v]`.
[in]	dj	signed column offset in `[-radius_v, radius_v]`.

Returns: selected kernel weight.

Exceptions

std::out_of_range if the offset is outside the kernel.

Definition at line 185 of file ca-kernels.H.

References ah_out_of_range_error_if, Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Kernel2D< T, Rows, Cols >::index(), r, Aleph::CA::Kernel2D< T, Rows, Cols >::radius_v, and Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

◆ weights()

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr const std::array< T, size_v > & Aleph::CA::Kernel2D< T, Rows, Cols >::weights ( ) const

inlineconstexprnoexcept

Return the raw row-major weight array.

Returns: const reference to the stored weights.

Exceptions

This	function does not throw.

Definition at line 238 of file ca-kernels.H.

References Aleph::CA::Kernel2D< T, Rows, Cols >::weights_.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D().

Member Data Documentation

◆ cols_v

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::cols_v = Cols

staticconstexpr

Number of columns.

Definition at line 96 of file ca-kernels.H.

◆ neighbour_count_v

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_count_v = size_v - 1

staticconstexpr

Number of neighbour weights excluding the centre.

Definition at line 100 of file ca-kernels.H.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::apply(), and Aleph::CA::Kernel2D< T, Rows, Cols >::neighbour_weight().

◆ radius_v

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::radius_v = Rows / 2

staticconstexpr

Chebyshev radius matched by Moore<2, radius_v>.

Definition at line 102 of file ca-kernels.H.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::weight_at_offset().

◆ rows_v

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::rows_v = Rows

staticconstexpr

Number of rows.

Definition at line 94 of file ca-kernels.H.

◆ size_v

template<typename T , std::size_t Rows, std::size_t Cols>

constexpr std::size_t Aleph::CA::Kernel2D< T, Rows, Cols >::size_v = Rows * Cols

staticconstexpr

Total number of weights including the centre.

Definition at line 98 of file ca-kernels.H.

Referenced by Aleph::CA::Kernel2D< T, Rows, Cols >::Kernel2D().

◆ weights_

template<typename T , std::size_t Rows, std::size_t Cols>

std::array<T, size_v> Aleph::CA::Kernel2D< T, Rows, Cols >::weights_ {}

private

Definition at line 105 of file ca-kernels.H.

The documentation for this class was generated from the following file:

ca-kernels.H

Public Types

Public Member Functions

Static Public Attributes

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ Kernel2D() [1/4]

◆ Kernel2D() [2/4]

◆ Kernel2D() [3/4]

◆ Kernel2D() [4/4]

Member Function Documentation

◆ apply()

◆ center()

◆ index()

◆ neighbour_weight()

◆ operator()()

◆ sum()

◆ to_matrix()

◆ weight_at_offset()

◆ weights()

Member Data Documentation

◆ cols_v

◆ neighbour_count_v

◆ radius_v

◆ rows_v

◆ size_v

◆ weights_