sht_reconstruction_comparison

hrtfpykit.plots.sht_reconstruction_comparison(hrtf, reconstructed_magnitude, position='front', ear='left', x_axis='linear', unit='db', reference=1.0, freq_min=None, freq_max=None, show=True)

Compare original and SH-reconstructed HRTF magnitude spectra.

This diagnostic plot overlays the magnitude stored in TF with a magnitude matrix reconstructed from spherical-harmonic coefficients, typically the output of sht_inverse(). It is used to inspect how well a selected spherical-harmonic order reproduces the spectral detail of one source direction and one ear.

The function resolves position against the current HRTF source grid through the same spherical-position query path used by the main HRTF plotting methods. It then selects the corresponding original TF magnitude, extracts the matching reconstructed magnitude trace, converts both traces when unit=``db``, and draws them on a single frequency-axis plot.

Notes

reconstructed_magnitude must contain linear reconstructed magnitude values, not decibels. Passing unit as db affects only the plotted values. In dB mode, absolute magnitudes are converted with a small positive floor so unconstrained SH reconstructions with negative fitted values can be displayed. If reference is max, both traces are normalized by the maximum absolute magnitude across the selected original and reconstructed spectra before conversion to decibels.

The function creates a new Figure with a single axis and returns None.

Parameters:

  • hrtf (HRTF) – HRTF object providing the reference complex TF data, frequency bins, and source-grid metadata. TF.values must have shape (positions, ears, frequency_bins) and include at least two ear channels.

  • reconstructed_magnitude (np.ndarray) – Reconstructed linear magnitude values. Use shape (N, F) for a single-ear spherical-harmonic reconstruction or (N, 2, F) for a two-ear reconstruction produced with ear=``both``. The first axis must match the HRTF source-position axis and the final axis must match TF.frequency_bins.

  • position (np.ndarray | list | tuple | str, default=``front``) – Single spatial query resolved on the HRTF source grid. Named positions such as front, back, left, and right are accepted. Numeric queries use spherical coordinates in degrees as [azimuth, elevation].

  • ear ({left, right}, default=``left``) – Ear channel used for the original HRTF trace and, when reconstructed_magnitude has an ear axis, for the reconstructed trace. For a single-ear reconstruction with shape (N, F), choose the ear that was used when computing the SH coefficients.

  • x_axis ({linear, log}, default=``linear``) – Frequency-axis scale used for the plot.

  • unit ({db, linear}, default=``db``) – Magnitude unit used on the y axis.

  • reference (float | str, default=1.0) – Reference used when unit=``db``. Passing max normalizes both traces by the maximum magnitude across the selected original and reconstructed spectra.

  • freq_min (float | None, default=None) – Lower frequency bound in hertz. When omitted, the minimum available frequency bin is used.

  • freq_max (float | None, default=None) – Upper frequency bound in hertz. When omitted, the maximum available frequency bin is used.

  • show (bool, default=True) – If True, call matplotlib.pyplot.show() before returning.

Returns:

The function creates and configures a Matplotlib figure as a side effect.

Return type:

None

Raises:

ValueError – If TF values or frequency bins are unavailable, if ear, x_axis, or unit is unsupported, if position does not resolve to exactly one source position, if original or reconstructed arrays have incompatible shapes, if the selected position is out of bounds, if the frequency-bin axis does not match the selected magnitude trace, if frequency bounds are invalid, or if no frequency bins fall inside the selected range.

Examples

Compare a two-ear SH reconstruction against the original left-ear HRTF magnitude at the front direction:

>>> from hrtfpykit.hrtf import load_hrtf, sht, sht_inverse
>>> from hrtfpykit.plots import sht_reconstruction_comparison
>>> hrtf = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> sh_representation = sht(hrtf, sh_order=8, ear="both")
>>> sh_representation.C.shape
(81, 2, 129)
>>> reconstructed = sht_inverse(sh_representation)
>>> reconstructed.shape
(793, 2, 129)
>>> sht_reconstruction_comparison(
...     hrtf=hrtf,
...     reconstructed_magnitude=reconstructed,
...     position="front",
...     ear="left",
...     x_axis="log",
...     unit="db",
...     reference="max",
...     freq_min=200.0,
...     freq_max=16000.0,
... )