compare_itd

hrtfpykit.plots.compare_itd(hrtfs, plane_angle=0.0, azimuth_range_mode='0-360', legends=None, line_colors=None, line_styles=None, legend_location=None, legend_bbox_to_anchor=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Compare signed ITD curves from several HRTFs.

compare_itd calls itd() for each HRTF as itd(hrtf, method="threshold", output="time", thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=False). For every HRTF, it selects the nearest measured horizontal plane from that HRTF source grid, sorts sources by azimuth, and overlays signed ITD in microseconds.

The plotted values keep the sign convention of itd(). azimuth_range_mode="-180-180" reverses the displayed x axis so listener left appears on the left side of the figure.

Parameters:

  • hrtfs (list[HRTF]) – HRTF objects to compare. The list must contain at least 2 and at most 5 entries. Every object must contain IR data and an IR sample rate.

  • plane_angle (float, default=0.0) – Requested horizontal plane elevation in degrees. The nearest available elevation is selected separately for each HRTF.

  • azimuth_range_mode ({0-360, -180-180}, default=``0-360``) – Azimuth convention used on 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.

  • legends (list[str] | tuple[str, ...] | None, default=None) – Subject legend labels. Defaults to subject_1 through subject_n.

  • line_colors (list[str] | tuple[str, ...] | None, default=None) – One line color per subject. Uses the default color cycle when omitted.

  • line_styles (list[str] | tuple[str, ...] | None, default=None) – One line style per subject. Defaults to solid lines.

  • legend_location (str | None, default=None) – Legend location. Defaults to upper right.

  • legend_bbox_to_anchor (tuple[float, float] | None, default=None) – Optional legend anchor tuple (x, y).

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

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

  • 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 overlaid signed ITD curves.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If the HRTF list length, plane_angle, azimuth range, legend/style lengths, IR availability, sample rate availability, selected plane, or computed ITD shape is invalid.

Warns:

HRTFPyKitWarning – If HRTFs resolve the requested horizontal plane to different real elevations.

Notes

The plot uses one Cartesian axis and overlays all HRTFs in the same coordinate frame. Curves can have different azimuth sample locations when the HRTFs use different source grids.

Examples

Compare the signed ITD curve around the horizontal plane:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_itd
>>> hrtf_a = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("P0002_FreeFieldComp_44kHz.sofa")
>>> compare_itd(
...     [hrtf_a, hrtf_b],
...     plane_angle=0.0,
...     legends=["P0001", "P0002"],
...     line_styles=["-", "--"],
... )