Support functions for 3D table interpolation. More...

#include "table3d_interpolate.h"
#include "maths.h"
#include "unit_testing.h"
#include "table2d.h"

Classes
struct	row_col2d
	Row and column coordinates in a 2D table. More...

Functions
Interpolation
TESTABLE_INLINE_STATIC QU1X8_t	compute_bin_position (const uint16_t &value, const table3d_dim_t &upperBinIndex, const table3d_axis_t *pAxis, const uint16_t &multiplier)
	Compute the % position of a value within a bin.

static row_col2d	toTopRight (const xy_coord2d &axisCoords, const table3d_dim_t &axisSize)
	Get the top right corner of the value coordinates in a 3D table, based on x/y axis coords.

static row_col2d	toBottomLeft (const row_col2d &topRight, const table3d_dim_t &axisSize)
	Get the bottom left corner of the value coordinates in a 3D table, based on top right corner.

TESTABLE_INLINE_STATIC table3d_value_t	bilinear_interpolation (const table3d_value_t &tl, const table3d_value_t &tr, const table3d_value_t &bl, const table3d_value_t &br, const QU1X8_t &dx, const QU1X8_t &dy)
	2d interpolation, given 4 corner values and x/y percentages

table3d_value_t	interpolate_3d_value (const xy_values &lookUpValues, const xy_coord2d &upperBinIndices, const table3d_dim_t &axisSize, const table3d_value_t pValues, const table3d_axis_t pXAxis, const uint16_t xMultiplier, const table3d_axis_t *pYAxis, const uint16_t yMultiplier)
	Interpolate a table value from axis bins & values.

Axis Bin Searching
using	table3d_bin_t = _table2d_detail::Bin< table3d_axis_t >
	Perform a linear search on an array for the bin that contains value.

TESTABLE_INLINE_STATIC table3d_dim_t	linear_bin_search (const table3d_axis_t *pStart, const table3d_dim_t length, const table3d_axis_t value)
	Perform a linear search on an array for the bin that contains value.

table3d_dim_t	find_bin_max (const table3d_axis_t &value, const table3d_axis_t *pAxis, table3d_dim_t length, table3d_dim_t lastBinMax)
	Find the bin that covers the test value.

Fixed point math
typedef uint16_t	QU1X8_t
	Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

constexpr QU1X8_t	QU1X8_INTEGER_SHIFT = 8
	Integer shift to convert to/from QU1X8_t.

TESTABLE_CONSTEXPR QU1X8_t	QU1X8_ONE = toQU1X8(1U)
	Precomputed value of 1 in QU1X8_t.

TESTABLE_CONSTEXPR QU1X8_t	QU1X8_HALF = QU1X8_ONE/2U
	Precomputed value of 0.5 in QU1X8_t.

static constexpr QU1X8_t	toQU1X8 (uint16_t base)
	Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

static constexpr uint16_t	fromQU1X8 (QU1X8_t base)
	Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

TESTABLE_INLINE_STATIC QU1X8_t	mulQU1X8 (QU1X8_t a, QU1X8_t b)
	Multiply two QU1X8_t values.

Detailed Description

Support functions for 3D table interpolation.

Typedef Documentation

◆ QU1X8_t

typedef uint16_t QU1X8_t

Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

See also: https://en.wikipedia.org/wiki/Q_(number_format).

This is specialised for the number range 0..1 - a generic fixed point class would miss some important optimisations. Specifically, we can avoid type promotion during multiplication.

◆ table3d_bin_t

using table3d_bin_t = _table2d_detail::Bin<table3d_axis_t>

Perform a linear search on an array for the bin that contains value.

Note: Assume array is ordered [max...min]

Parameters

pStart	Pointer to the start of the array.
length	Length of the array.
value	Value to search for.

Returns: Upper array index of the bin

Function Documentation

◆ bilinear_interpolation()

TESTABLE_INLINE_STATIC table3d_value_t bilinear_interpolation	(	const table3d_value_t &	tl,
		const table3d_value_t &	tr,
		const table3d_value_t &	bl,
		const table3d_value_t &	br,
		const QU1X8_t &	dx,
		const QU1X8_t &	dy
	)

2d interpolation, given 4 corner values and x/y percentages

 tl----------------tr
 |                 |
 |                 |
 |                 |
 |>>>>>dx>>>>?     |
 |           ^     |
 |           dy    |
 |           ^     |
 bl----------------br

Parameters

tl	Top left value
tr	Top right value
bl	Bottom left value
br	Bottom right value
dx	X distance
dy	Y distance

Returns: table3d_value_t

Here is the call graph for this function:

Here is the caller graph for this function:

◆ compute_bin_position()

TESTABLE_INLINE_STATIC QU1X8_t compute_bin_position	(	const uint16_t &	value,
		const table3d_dim_t &	upperBinIndex,
		const table3d_axis_t *	pAxis,
		const uint16_t &	multiplier
	)

Compute the % position of a value within a bin.

0%==at/below the bin minimum
100%==at/above the bin maximum
50%==in the middle of the bin.

Note: The multiplier is used to scale the axis values to the same scale as the value being checked. This retains the full precision of the axis values, thus the computed position and eventually the final interpolated result

Parameters

value	The value to check.
upperBinIndex	The upper bin index into pAxis.
pAxis	The axis array.
multiplier	The multiplier for the axis values.

Returns: QU1X8_t The % position of the value within the bin.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ find_bin_max()

table3d_dim_t find_bin_max	(	const table3d_axis_t &	value,
		const table3d_axis_t *	pAxis,
		table3d_dim_t	length,
		table3d_dim_t	lastBinMax
	)

Find the bin that covers the test value.

For example, 4 in { 1, 3, 5, 7, 9 } would be 2

Note: We assume the axis is in [max..min] order.

Parameters

value	The value to search for.
pAxis	The axis to search.
length	The length of the axis.
lastBinMax	The last bin max.

Returns: table3d_dim_t The axis index for the top of the bin.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fromQU1X8()

static constexpr uint16_t fromQU1X8 ( QU1X8_t base )

inlinestaticconstexpr

Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

See also: https://en.wikipedia.org/wiki/Q_(number_format).

This is specialised for the number range 0..1 - a generic fixed point class would miss some important optimisations. Specifically, we can avoid type promotion during multiplication.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ interpolate_3d_value()

table3d_value_t interpolate_3d_value	(	const xy_values &	lookUpValues,
		const xy_coord2d &	upperBinIndices,
		const table3d_dim_t &	axisSize,
		const table3d_value_t *	pValues,
		const table3d_axis_t *	pXAxis,
		const uint16_t	xMultiplier,
		const table3d_axis_t *	pYAxis,
		const uint16_t	yMultiplier
	)

Interpolate a table value from axis bins & values.

Parameters

lookUpValues	The x & y axis values we are interpolating
upperBinIndices	The x & y axis bin indices that contain lookUpValues
axisSize	The length of an axis
pValues	The interpolation source values
pXAxis	The x-axis
xMultiplier	The x-axis multiplier
pYAxis	The y-axis
yMultiplier	The y-axis multiplier

Returns: table3d_value_t

Here is the call graph for this function:

Here is the caller graph for this function:

◆ linear_bin_search()

TESTABLE_INLINE_STATIC table3d_dim_t linear_bin_search	(	const table3d_axis_t *	pStart,
		const table3d_dim_t	length,
		const table3d_axis_t	value
	)

Perform a linear search on an array for the bin that contains value.

Note: Assume array is ordered [max...min]

Parameters

pStart	Pointer to the start of the array.
length	Length of the array.
value	Value to search for.

Returns: Upper array index of the bin

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mulQU1X8()

TESTABLE_INLINE_STATIC QU1X8_t mulQU1X8	(	QU1X8_t	a,
		QU1X8_t	b
	)

Multiply two QU1X8_t values.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toBottomLeft()

static row_col2d toBottomLeft	(	const row_col2d &	topRight,
		const table3d_dim_t &	axisSize
	)

inlinestatic

Get the bottom left corner of the value coordinates in a 3D table, based on top right corner.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toQU1X8()

static constexpr QU1X8_t toQU1X8 ( uint16_t base )

inlinestaticconstexpr

Unsigned fixed point number type with 1 integer bit & 8 fractional bits.

See also: https://en.wikipedia.org/wiki/Q_(number_format).

This is specialised for the number range 0..1 - a generic fixed point class would miss some important optimisations. Specifically, we can avoid type promotion during multiplication.

Here is the call graph for this function:

◆ toTopRight()

static row_col2d toTopRight	(	const xy_coord2d &	axisCoords,
		const table3d_dim_t &	axisSize
	)

inlinestatic

Get the top right corner of the value coordinates in a 3D table, based on x/y axis coords.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ QU1X8_HALF

TESTABLE_CONSTEXPR QU1X8_t QU1X8_HALF = QU1X8_ONE/2U

Precomputed value of 0.5 in QU1X8_t.

◆ QU1X8_INTEGER_SHIFT

constexpr QU1X8_t QU1X8_INTEGER_SHIFT = 8

constexpr

Integer shift to convert to/from QU1X8_t.

◆ QU1X8_ONE

TESTABLE_CONSTEXPR QU1X8_t QU1X8_ONE = toQU1X8(1U)

Precomputed value of 1 in QU1X8_t.

Classes

Functions

Axis Bin Searching

Fixed point math

Detailed Description

Typedef Documentation

◆ QU1X8_t

◆ table3d_bin_t

Function Documentation

◆ bilinear_interpolation()

◆ compute_bin_position()

◆ find_bin_max()

◆ fromQU1X8()

◆ interpolate_3d_value()

◆ linear_bin_search()

◆ mulQU1X8()

◆ toBottomLeft()

◆ toQU1X8()

◆ toTopRight()

Variable Documentation

◆ QU1X8_HALF

◆ QU1X8_INTEGER_SHIFT

◆ QU1X8_ONE