clarity.data.HOA_tools_cec2 module

Tools to support higher order ambisonic processing.

class clarity.data.HOA_tools_cec2.HOARotator(order, resolution)

Bases: object

Provides methods for rotating ambisonics.

rotate(signal: ndarray, rotation_vector: ndarray) → ndarray

Apply rotation to HOA signals using precomputed rotation matrices.

Parameters:

• signal (array-like) – ambisonic signals

• rotation_vector (array-like) – rotation vector (in radians)

Returns:

transformed ambisonic signals

Return type:

array-like

clarity.data.HOA_tools_cec2.P(i: int, a: int, b: int, order: int, rotation_matrices: numba.typed.List) → numba.typed.List

P function for rotation matrix calculation.

Parameters:

• i (int) – index

• a (int) – ‘a’ value

• b (int) – ‘b’ value

• order (int) – order

• r (list(matrix)) – rotation matrices

Returns:

P value

Return type:

float

clarity.data.HOA_tools_cec2.U(degree: int, n: int, order: int, rotation_matrices: numba.typed.List) → numba.typed.List

U coefficient initialiser for rotation matrix calculation.

Parameters:

• rotation_degree (int) – Upper parameters of spherical harmonic component Y and n the lower.

• n (int) – index

• order (int) – order

• rotation_matrices (list(matrix)) – rotation matrices

Returns:

U value

Return type:

float

clarity.data.HOA_tools_cec2.V(degree: int, n: int, order: int, rotation_matrices: numba.typed.List) → numba.typed.List

V coefficient initialiser for rotation matrix calculation.

Parameters:

• degree (int) – valid inputs are int(|m|) <= order.

• n (int) – index

• order (int) – order

• rotation_matrices (list(matrix)) – rotation matrices

Returns:

V value

Return type:

float

clarity.data.HOA_tools_cec2.W(degree: int, n: int, order: int, rotation_matrices: numba.typed.List) → numba.typed.List

W coefficient initialiser for rotation matrix calculation.

Parameters:

• degree (int) – degree

• n (int) – index

• order (int) – order

• rotation_matrices (list(matrix)) – rotation matrices

Returns:

W value

Return type:

float

clarity.data.HOA_tools_cec2.ambisonic_convolve(signal: ndarray, hoa_impulse_responses: ndarray, order: int) → ndarray

Convolve HOA Impulse Responses with signals.

Parameters:

• signal (ndarray[samples]) – the signal to convole

• hoa_impulse_response (ndarray[samples, channels]) – the HOA impulse responses

• order (int, optional) – ambisonic order.

Returns:

the convolved signal

Return type:

np.ndarray[samples, channels]

clarity.data.HOA_tools_cec2.binaural_mixdown(ambisonic_signals: ndarray, hrir: dict[str, Any], hrir_metadata: dict[str, Any]) → ndarray

Perform binaural mixdown of ambisonic signals.

Parameters:

• ambisonic_signals (array-like) – inputs

• hrir_filename (string) – name of HRIR file

• hrir_metadata (dict) – data for channel selection and ambisonic decoding

Returns:

stereo audio

Return type:

array

clarity.data.HOA_tools_cec2.centred_element(reference: ndarray, row: int, col: int)

Get value from centered element indexing.

Parameters:

• reference (matrix) – reference input matrix

• row (int) – row index

• col (int) – column index

Returns:

matrix element

Return type:

Any

clarity.data.HOA_tools_cec2.compute_UVW_coefficients(degree, n, order)

Compute U, V and W coefficients for rotation matrix calculation.

Parameters:

• m (index) – degree

• n (index) – index

• el (index) – order

Returns:

u, v, w

Return type:

tuple

clarity.data.HOA_tools_cec2.compute_band_rotation(order: int, rotation_matrices: numba.typed.List, output)

Compute submatrix for rotation matrix.

Parameters:

• order (int) – order of submatrix

• rotationmatrices (list(matrix)) – previous and current submatrices

• output (matrix) – output destination

Returns:

rotation submatrix

Return type:

matrix

clarity.data.HOA_tools_cec2.compute_rms(input_signal: ndarray, axis: int = 0) → ndarray

Compute rms values along a given axis. :param input_signal: Input signal :type input_signal: np.ndarray :param axis: Axis along which to compute the Root Mean Square. 0 (default) or 1. :type axis: int

Returns:

Root Mean Square for the given axis.

Return type:

float

clarity.data.HOA_tools_cec2.compute_rotation_matrix(n: int, foa_rotmat: ndarray) → ndarray

Generate a rotation matrix to rotate HOA soundfield.

Based on [1]_ and [2]. Operates on HOA of a given order rotates by azimuth theta and elevation phi.

Parameters:

• order (int) – order of ambisonic soundfield

• foa_rotmat (arraylike) – rotation matrix to expand

Returns:

HOA rotation matrix

Return type:

np.ndarray

References: .. [1] Ivanic J, Ruedenberg K (1996) Rotation Matrices for Real Spherical Harmonics.

Direct Determination J. Phys. Chem. 1996, 100(15):6342–6347. Available at <https://pubs.acs.org/doi/10.1021/jp953350u> and <https://doi.org/10.1021/JP9833350>

[2]

Gorzel M, Allen A, Kelly I, Kammerl J, Gungormusler, A, Yeh H, Boland F Efficient Encoding and Decoding of Binaural Sound with Resonance Audio In Proc. of the AES International Conference on Immersive and Interactive Audio, March 2019. Available at <https://www.aes.org/e-lib/browse.cfm?elib=20446>

clarity.data.HOA_tools_cec2.compute_rotation_vector(start_angle: float, end_angle: float, signal_length: int, start_idx: int, end_idx: int) → ndarray

Compute the rotation vector.

Parameters:

• start_angle (float)

• end_angle (float)

• signal_length (int)

• start_idx (int)

• end_idx (int)

Returns:

_description_

Return type:

np.array

clarity.data.HOA_tools_cec2.convert_a_to_b_format(front_left_up: ndarray, front_right_down: ndarray, back_left_down: ndarray, back_right_up: ndarray)

Converts 1st order A format audio into 1st order B format. For more information on ambisonic formats see Gerzon, Michael A. “Ambisonics. Part two: Studio techniques.” (1975).

Parameters:

• front_left_up (np.ndarray) – Front-left-up audio

• front_right_down (np.ndarray) – Front-right-down audio

• back_left_down (np.ndarray) – Back-left-down audio

• back_right_up (np.ndarray) – Back-right-up audio

Raises:

• TypeError – input must be numpy array

• ValueError – all inputs must have same dimensions

Returns:

4xN array containing B-format audio. indexed w,x,y,z

Return type:

nd.array

clarity.data.HOA_tools_cec2.dB_to_gain(x: int | float) → float

Convert dB to gain.

Parameters:

x (float)

Returns

float:

clarity.data.HOA_tools_cec2.dot(A, B)

Wraps np.dot for numba #@njit.

Parameters:

• A (Array)

• B (Array)

Returns:

output

Return type:

Array

clarity.data.HOA_tools_cec2.equalise_rms_levels(inputs: list[ndarray]) → list[ndarray]

Equalise RMS levels.

Parameters:

inputs (array) – signals

Returns:

normalised signals

Return type:

array

clarity.data.HOA_tools_cec2.rotation_control_vector(array_length: int, start_index: int, end_index: int, smoothness: int = 1) → ndarray

Generate mapped rotation control vector for values of theta.

Parameters:

• array_length (int) – Length of array

• start_index (int) – Start position

• end_index (int)

• smoothness (int, optional)

Returns:

mapped rotation control vector

Return type:

array

clarity.data.HOA_tools_cec2.smoothstep(x: ndarray, x_min: float = 0.0, x_max: float = 1.0, N: int = 1) → ndarray

Apply the smoothstep function.

Parameters:

• x (np.ndarray) – input

• x_min (float, optional) – clamp minimum. Defaults to 0.

• x_max (float, optional) – clamp maximum. Defaults to 1.

• N (int, optional) – smoothing factor. Defaults to 1.

Returns:

smoothstep values

Return type:

np.ndarray