directivity

Frequency directivity

Since R2024a

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.

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.

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

Examples

Compute Directivity of HRTF Data

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])

Compute Directivity for All Measurements

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")

Input Arguments

s — SOFA object

SimpleFreeFieldHRIR object | SimpleFreeFieldHRSOS object | SimpleFreeFieldHRTF object

SOFA object, specified as one of the following objects.

• SimpleFreeFieldHRIR

• SimpleFreeFieldHRSOS

• SimpleFreeFieldHRTF

f — Frequency

positive scalar | vector

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")

NPoints — Number of frequency points in spectrum

max(2048,L) (default) | positive integer

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

Receiver — Indices of receivers

1 (default) | vector of positive integers

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

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

Plane — Plane

"horizontal" (default) | "median" | "sagittal"

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

This argument applies only when Specification is "plane".

Data Types: char | string

PlaneOffsetAngle — Plane offset angle

0 (default) | value in range [-90,90]

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

AngleTolerance — Angle tolerance

1 (default) | positive scalar

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

InterpolateHRTF — Use interpolated HRTF measurements

false (default) | true

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

Specification — Measurements specification

"plane" (default) | "measurements"

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

MeasurementIndex — Indices of measurements

vector of positive integers

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

d — Directivity

N-by-M-by-R array

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.

ang — Angles

vector

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