compare_ild_difference

hrtfpykit.plots.compare_ild_difference(hrtf_reference, hrtfs, epsilon=1e-12, 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 broad band ILD difference values over the reference source grid.

compare_ild_difference calls ild_difference() as ild_difference(hrtf_reference=hrtf_reference, hrtfs=hrtfs, mode="broad-band", epsilon=epsilon, absolute=absolute, reduction_axis="ilds", reduction_method=reduction_method). The result is one ILD difference value in dB 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 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.

  • epsilon (float, default=1e-12) – Positive floor passed to ild_difference() before level ratio conversion.

  • absolute (bool, default=True) – Difference sign handling. True plots absolute ILD 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 broad band ILD difference source map.

Return type:

matplotlib.figure.Figure

Raises:

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

Examples

Plot broad band ILD difference magnitudes as measured source markers:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_ild_difference
>>> hrtf_reference = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_compared = load_hrtf("P0002_FreeFieldComp_44kHz.sofa")
>>> compare_ild_difference(
...     hrtf_reference,
...     hrtf_compared,
...     absolute=True,
...     plot_type="scatter",
...     colormap="plasma",
... )