sht

hrtfpykit.hrtf.sht(tf, sh_order, ear='left', epsilon=1e-06)

Compute a spherical-harmonic decomposition of HRTF magnitudes.

The function projects linear HRTF magnitudes from the source grid into a real-valued spherical-harmonic basis. It accepts either an HRTF object or its linked TF domain object. In both cases, the linked HRTF source grid is used to evaluate the basis. The complex transfer functions stored in TF.values are decomposed by magnitude.

The source coordinates are read as spherical positions in radians. The implementation maps SOFA-style azimuth/elevation to spherical-harmonic angles where phi is the azimuth and theta is pi / 2 minus elevation before evaluating scipy.special.sph_harm_y. Coefficients are solved with Tikhonov regularization.

Parameters:

  • tf (TF | HRTF) – Input frequency-domain domain object or HRTF object. The values stored in TF.values must have shape (positions, ears, frequency_bins) and contain at least two ear channels. The bins stored in TF.frequency_bins must match the final TF axis.

  • sh_order (int) – Non-negative spherical-harmonic order. The coefficient count is (sh_order + 1) ** 2.

  • ear ({left, right, both}, default=``left``) – Ear channel used for the decomposition. left and right produce a two-dimensional coefficient matrix. both preserves a two-ear axis in the coefficient matrix.

  • epsilon (float, default=1e-6) – Positive Tikhonov regularization factor added to the normal matrix. Larger values stabilize ill-conditioned source grids more strongly but increase regularization bias.

Returns:

SH-domain container with C shaped (n_coefficients, n_frequencies) for one ear or (n_coefficients, 2, n_frequencies) for both ears, and Y shaped (N, n_coefficients).

Return type:

SH

Raises:

ValueError – If tf is not an HRTF or linked TF object, TF values or frequency bins are missing, TF shape is incompatible, the source grid does not match the TF position axis, ear is invalid, sh_order is not a non-negative integer, or epsilon is not finite and positive.

Examples

Compute a low-order spherical-harmonic representation from a SOFA-backed HRTF and keep both ears in the coefficient tensor:

>>> from hrtfpykit.hrtf import load_hrtf, sht
>>> hrtf = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> sh = sht(hrtf, sh_order=3, ear="both")
>>> sh.get_coefficients().shape
(16, 2, 129)