# directivity

Frequency directivity

Since R2024a

## Syntax

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

## Description

example

````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.```

example

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

example

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

## Examples

collapse all

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

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

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:

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