Main Content

# directivity

System object: phased.CustomMicrophoneElement
Package: phased

Directivity of custom microphone element

## Syntax

```D = directivity(H,FREQ,ANGLE) ```

## Description

`D = directivity(H,FREQ,ANGLE)` returns the Directivity (dBi) of a custom microphone element, `H`, at frequencies specified by `FREQ` and in direction angles specified by `ANGLE`.

## Input Arguments

expand all

Custom microphone element specified as a `phased.CustomMicrophoneElement` System object.

Example: `H = phased.CustomMicrophoneElement;`

Frequencies for computing directivity and patterns, specified as a positive scalar or 1-by-L real-valued row vector. Frequency units are in hertz.

• For an antenna, microphone, or sonar hydrophone or projector element, `FREQ` must lie within the range of values specified by the `FrequencyRange` or `FrequencyVector` property of the element. Otherwise, the element produces no response and the directivity is returned as `–Inf`. Most elements use the `FrequencyRange` property except for `phased.CustomAntennaElement` and `phased.CustomMicrophoneElement`, which use the `FrequencyVector` property.

• For an array of elements, `FREQ` must lie within the frequency range of the elements that make up the array. Otherwise, the array produces no response and the directivity is returned as `–Inf`.

Example: `[1e8 2e6]`

Data Types: `double`

Angles for computing directivity, specified as a 1-by-M real-valued row vector or a 2-by-M real-valued matrix, where M is the number of angular directions. Angle units are in degrees. If `ANGLE` is a 2-by-M matrix, then each column specifies a direction in azimuth and elevation, `[az;el]`. The azimuth angle must lie between –180° and 180°. The elevation angle must lie between –90° and 90°.

If `ANGLE` is a 1-by-M vector, then each entry represents an azimuth angle, with the elevation angle assumed to be zero.

The azimuth angle is the angle between the x-axis and the projection of the direction vector onto the xy plane. This angle is positive when measured from the x-axis toward the y-axis. The elevation angle is the angle between the direction vector and xy plane. This angle is positive when measured towards the z-axis. See Azimuth and Elevation Angles.

Example: `[45 60; 0 10]`

Data Types: `double`

## Output Arguments

expand all

Directivity, returned as an M-by-L matrix. Each row corresponds to one of the M angles specified by `ANGLE`. Each column corresponds to one of the L frequency values specified in `FREQ`. Directivity units are in dBi where dBi is defined as the gain of an element relative to an isotropic radiator.

## Examples

expand all

Compute the directivity of a custom microphone element. Create a custom cardioid microphone, and plot the microphone's response at 700 Hz for elevations between -90 and +90 degrees.

Define the pattern for the custom microphone element. The System object's `PolarPatternAngles` property has default value of `[-180:180]` degrees.

```myAnt = phased.CustomMicrophoneElement; myAnt.PolarPatternFrequencies = [500 1000]; myAnt.PolarPattern = mag2db([... 0.5+0.5*cosd(myAnt.PolarPatternAngles);... 0.6+0.4*cosd(myAnt.PolarPatternAngles)]);```

Calculate the directivity as a function of elevation at zero degrees azimuth.

```elev = [-90:5:90]; azm = zeros(size(elev)); ang = [azm;elev]; freq = 700; d = directivity(myAnt,freq,ang); plot(elev,d) xlabel('Elevation (deg)') ylabel('Directivity (dBi)')```

The directivity is maximum at ${0}^{\circ }$ elevation.

expand all