Main Content

directivity

Frequency directivity

Since R2024a

collapse all in page

    Syntax

    d = directivity(s,f)
    d = directivity(s,f,Name=Value)
    [d,ang] = directivity(___)
    directivity(___)

    Description

    d = directivity(s,f) returns the directivity of the specified frequency in the horizontal plane at zero elevation. The directivity measures the level of received sound in dB of specific frequencies from different directions in the plane.

    example

    d = directivity(s,f,Name=Value) specifies options using one or more name-value arguments.

    [d,ang] = directivity(___) also returns the angles corresponding to the measurements.

    example

    directivity(___) with no output arguments creates a directivity plot.

    example

    Examples

    collapse all

    Open Live Script

    Read in a SOFA file containing HRTF measurements.

    s = sofaread("ReferenceHRTF.sofa");

    Compute the directivity of the HRTF data at 750 Hz and 1500 Hz in the horizontal plane at zero elevation.

    [d,azi] = directivity(s,[750 1500]);

    Call directivity with no output arguments to plot the directivity.

    directivity(s,[750 1500])

    Figure contains an axes object with type polaraxes. The polaraxes object contains 2 objects of type line. These objects represent 750.000000 Hz, 1500.000000 Hz.

    Open Live Script

    Read in a SOFA file containing HRTF measurements.

    s = sofaread("ReferenceHRTF.sofa");

    Call directivity with Specification set to "measurements" to compute the directivity at 750 Hz for all HRTF measurements in the SOFA file.

    d = directivity(s,750,Specification="measurements");

    Call directivity with no output arguments to visualize the directivity for all measurements.

    directivity(s,750,Specification="measurements")

    Figure contains an axes object. The axes object with title Frequency directivity at 750 Hz. Receiver 1., xlabel X (meters), ylabel Y (meters) contains an object of type patch.

    Input Arguments

    collapse all

    SOFA object, specified as one of the following objects.

    Frequency in Hz for which to compute the directivity, specified as a positive scalar or a vector of frequencies.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: directivity(s,750,Specification="measurements")

    Number of frequency points in the computed spectrum, specified as a positive integer. By default, the length of the frequency response is max(2048,L), where L is the length of the HRTF impulse responses.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Indices of the receivers, specified as a vector of positive integers.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Plane to compute the directivity, specified as "horizontal", "median", or "sagittal".

    This argument applies only when Specification is "plane".

    Data Types: char | string

    Plane offset angle in degrees, specified as a value in the range [-90,90]. This angle specifies the offset by which the Plane is shifted.

    This argument only applies to the horizontal and sagittal planes. For the horizontal plane, the offset corresponds to the elevation angle. For the sagittal plane, the offset corresponds to the lateral angle.

    This argument applies only when Specification is "plane".

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Angle tolerance in degrees, specified as a positive scalar. The function computes the directivity of the measurements within the tolerance of the plane specified by Plane and PlaneOffsetAngle.

    This argument applies only when Specification is "plane".

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Use interpolated HRTF measurements, corresponding to 100 uniformly-spaced points in the specified plane, to compute the directivity. Set this argument to true if the plane specified by Plane, PlaneOffsetAngle, and AngleTolerance does not contain a sufficient number of HRTF measurements. The function uses the bilinear interpolation method.

    This argument applies only when Specification is "plane".

    Data Types: logical

    Measurements specification, specified as "plane" or "measurements". Set this argument to "plane" to use Plane, PlaneOffsetAngle, and AngleTolerance to specify the plane over which to compute the directivity. Set this argument to "measurements" to use MeasurementIndex to select the specific measurements for which to compute the directivity.

    Data Types: char | string

    Indices of measurements to use, specified as a vector of positive integers. The indices must correspond to measurements in the data of the SOFA object s. By default, the function includes all measurements.

    This argument only applies when you set Specification to "measurements".

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Output Arguments

    collapse all

    Directivity in dB, returned as an N-by-M-by-R array, where:

    • N is the number of frequency points defined by NPoints.

    • M is the number of selected measurements.

    • R is the number of selected receivers defined by Receiver.

    Angles in degrees corresponding to the measurements used to compute the directivity, returned as a vector. The interpretation of the angles depends on the specified Plane.

    • For the horizontal plane, the angles correspond to the azimuth.

    • For the median plane, the angles correspond to the elevation.

    • For the sagittal plane, the angles correspond to the polar angles.

    The directivity function only returns this argument when Specification is "plane".

    Algorithms

    The directivity function measures the directivity of a frequency in a specified plane according the algorithm described in [1].

    References

    [1] Lee, Gyeong-Tae, Sang-Min Choi, Byeong-Yun Ko, and Yong-Hwa Park. "HRTF measurement for accurate sound localization cues." arXiv preprint arXiv:2203.03166 (2022).

    Version History

    Introduced in R2024a

    See Also

    | | | | | | | |

    Topics