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, show_titles=True, show_labels=True, show_legends=True)

Compare original and spherical harmonic reconstructed magnitude spectra.

sht_reconstruction_comparison reads the original magnitude from hrtf.TF.values and compares it with reconstructed_magnitude, typically produced by sht_inverse(). It resolves one source query with hrtf.Sources.get_position_index(...), selects the requested ear, applies the requested frequency range, and overlays original and reconstructed magnitude traces.

When unit="db", both traces are converted to decibels. reference="max" normalizes the plotted traces by the maximum magnitude across the selected original and reconstructed values.

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, display the figure before returning.

  • show_titles (bool, default=True) – If False, suppress generated subplot titles.

  • show_labels (bool, default=True) – If False, suppress generated axis labels.

  • show_legends (bool, default=True) – If False, suppress generated legends.

Returns:

Figure containing the original and reconstructed magnitude traces.

Return type:

matplotlib.figure.Figure

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("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,
... )