compare_itd_difference

hrtfpykit.plots.compare_itd_difference(hrtf_reference, hrtfs, method='threshold', output='time', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=True, reduction_method='mean', azimuth_range_mode='0-360', plot_type='heatmap', colormap='jet', show=True, show_titles=True, show_labels=True, show_legends=True)

Plot ITD difference values over the reference source grid.

compare_itd_difference calls itd_difference() as itd_difference(hrtf_reference=hrtf_reference, hrtfs=hrtfs, method=method, output=output, thresh_level=thresh_level, upper_cut_freq=upper_cut_freq, filter_order=filter_order, absolute=absolute, reduction_axis="itds", reduction_method=reduction_method). The result is one ITD difference value per source position after reducing the compared HRTF axis when several HRTFs are provided.

Source coordinates are read from hrtf_reference.Sources in spherical degrees. plot_type="scatter" colors the measured source positions directly, while plot_type="heatmap" interpolates the same source values onto an azimuth and elevation image grid.

Parameters:

  • hrtf_reference (HRTF) – Reference HRTF. It must provide IR data, an IR sample rate, and the source grid used for the plot coordinates.

  • hrtfs (HRTF or sequence of HRTF) – Compared HRTF object or objects. Every compared HRTF must use the same source positions as hrtf_reference. Several compared HRTFs are reduced into one source map with reduction_method.

  • method ({threshold, maxiacce}, default=``threshold``) – ITD estimator passed to itd_difference().

  • output ({time, samples}, default=``time``) – Unit used for ITD values and the colorbar label. time returns microseconds. samples returns sample offsets.

  • thresh_level (float, default=-10.0) – Threshold offset passed to the threshold ITD estimator.

  • upper_cut_freq (float, default=3000.0) – Low pass cutoff frequency in hertz used by the ITD estimator.

  • filter_order (int, default=10) – Filter order used by the ITD estimator.

  • absolute (bool, default=True) – Difference sign handling. True plots absolute ITD differences; False plots signed compared - reference differences.

  • reduction_method ({mean, rms}, default=``mean``) – Method used to reduce the compared HRTF axis when hrtfs contains several HRTFs.

  • azimuth_range_mode ({0-360, -180-180}, default=``0-360``) – Azimuth convention applied to the x axis. 0-360 follows the SOFA anticlockwise convention: front is 0 degrees, listener left is 90 degrees, back is 180 degrees, and listener right is 270 degrees. -180-180 wraps listener right to -90 degrees and reverses the displayed x axis so listener left appears visually left.

  • plot_type ({scatter, heatmap}, default=``heatmap``) – Source map renderer. scatter plots measured sources as colored markers. heatmap plots an interpolated azimuth/elevation color image.

  • colormap (str, default=``jet``) – Colormap name used for source map coloring.

  • show (bool, default=True) – If True, display the figure before returning.

  • show_titles (bool, default=True) – If True, adds the default figure title.

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

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

Returns:

Figure containing the ITD difference source map.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If ITD difference calculation fails, source positions are invalid, or the number of ITD difference values differs from the number of source positions.

Examples

Plot an interpolated ITD difference heatmap:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_itd_difference
>>> hrtf_reference = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_compared = load_hrtf("P0002_FreeFieldComp_44kHz.sofa")
>>> compare_itd_difference(
...     hrtf_reference,
...     hrtf_compared,
...     method="threshold",
...     output="time",
...     absolute=True,
...     plot_type="heatmap",
...     colormap="viridis",
... )