# pattern

System object: phased.CustomMicrophoneElement
Package: phased

Plot custom microphone element directivity and patterns

## Syntax

```pattern(sElem,FREQ) pattern(sElem,FREQ,AZ) pattern(sElem,FREQ,AZ,EL) pattern(___,Name,Value) [PAT,AZ_ANG,EL_ANG] = pattern(___) ```

## Description

`pattern(sElem,FREQ)` plots the 3-D array directivity pattern (in dBi) for the element specified in `sElem`. The operating frequency is specified in `FREQ`.

`pattern(sElem,FREQ,AZ)` plots the element directivity pattern at the specified azimuth angle.

`pattern(sElem,FREQ,AZ,EL)` plots the element directivity pattern at specified azimuth and elevation angles.

`pattern(___,Name,Value)` plots the element pattern with additional options specified by one or more `Name,Value` pair arguments.

`[PAT,AZ_ANG,EL_ANG] = pattern(___)` returns the element pattern in `PAT`. The `AZ_ANG` output contains the coordinate values corresponding to the rows of `PAT`. The `EL_ANG` output contains the coordinate values corresponding to the columns of `PAT`. If the `'CoordinateSystem'` parameter is set to `'uv'`, then `AZ_ANG` contains the U coordinates of the pattern and `EL_ANG` contains the V coordinates of the pattern. Otherwise, they are in angular units in degrees. UV units are dimensionless.

Note

This method replaces the `plotResponse` method. See Convert plotResponse to pattern for guidelines on how to use `pattern` in place of `plotResponse`.

## Input Arguments

expand all

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

Example: `sElem = 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`

Azimuth angles for computing directivity and pattern, specified as a 1-by-N real-valued row vector where N is the number of azimuth angles. Angle units are in degrees. Azimuth angles must lie between –180° and 180°.

The azimuth angle is the angle between the x-axis and the projection of the direction vector onto the xy plane. When measured from the x-axis toward the y-axis, this angle is positive.

Example: `[-45:2:45]`

Data Types: `double`

Elevation angles for computing directivity and pattern, specified as a 1-by-M real-valued row vector where M is the number of desired elevation directions. Angle units are in degrees. The elevation angle must lie between –90° and 90°.

The elevation angle is the angle between the direction vector and xy-plane. The elevation angle is positive when measured towards the z-axis.

Example: `[-75:1:70]`

Data Types: `double`

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

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Plotting coordinate system of the pattern, specified as the comma-separated pair consisting of `'CoordinateSystem'` and one of `'polar'`, `'rectangular'`, or `'uv'`. When `'CoordinateSystem'` is set to `'polar'` or `'rectangular'`, the `AZ` and `EL` arguments specify the pattern azimuth and elevation, respectively. `AZ` values must lie between –180° and 180°. `EL` values must lie between –90° and 90°. If `'CoordinateSystem'` is set to `'uv'`, `AZ` and `EL` then specify U and V coordinates, respectively. `AZ` and `EL` must lie between -1 and 1.

Example: `'uv'`

Data Types: `char`

Displayed pattern type, specified as the comma-separated pair consisting of `'Type'` and one of

• `'directivity'` — directivity pattern measured in dBi.

• `'efield'` — field pattern of the sensor or array. For acoustic sensors, the displayed pattern is for the scalar sound field.

• `'power'` — power pattern of the sensor or array defined as the square of the field pattern.

• `'powerdb'` — power pattern converted to dB.

Example: `'powerdb'`

Data Types: `char`

Display normalized pattern, specified as the comma-separated pair consisting of `'Normalize`' and a Boolean. Set this parameter to `true` to display a normalized pattern. This parameter does not apply when you set `'Type'` to `'directivity'`. Directivity patterns are already normalized.

Data Types: `logical`

Plotting style, specified as the comma-separated pair consisting of `'Plotstyle'` and either `'overlay'` or `'waterfall'`. This parameter applies when you specify multiple frequencies in `FREQ` in 2-D plots. You can draw 2-D plots by setting one of the arguments `AZ` or `EL` to a scalar.

Data Types: `char`

## Output Arguments

expand all

Element pattern, returned as an N-by-M real-valued matrix. The pattern is a function of azimuth and elevation. The rows of `PAT` correspond to the azimuth angles in the vector specified by `EL_ANG`. The columns correspond to the elevation angles in the vector specified by `AZ_ANG`.

Azimuth angles for displaying directivity or response pattern, returned as a scalar or 1-by-N real-valued row vector corresponding to the dimension set in `AZ`. The columns of `PAT` correspond to the values in `AZ_ANG`. Units are in degrees.

Elevation angles for displaying directivity or response, returned as a scalar or 1-by-M real-valued row vector corresponding to the dimension set in `EL`. The rows of `PAT` correspond to the values in `EL_ANG`. Units are in degrees.

## Examples

expand all

Design a cardioid microphone to operate in the frequency range between 500 and 1000 Hz.

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

Display a polar plot of an azimuth cut of the response at 500 Hz and 1000 Hz.

```fc = 500; pattern(sCustMike,[fc 2*fc],[-180:180],0,... 'CoordinateSystem','polar',... 'Type','powerdb');```

Plot the directivity as a line plot for the same two frequencies.

```pattern(sCustMike,[fc 2*fc],[-180:180],0,... 'CoordinateSystem','rectangular',... 'Type','directivity');```

Plot a $u$-cut of the power pattern of a custom cardioid microphone designed to operate in the frequency range 500-1000 Hz.

Create a cardioid microphone.

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

Plot the power pattern.

```fc = 500; pattern(sCustMike,fc,[-1:.01:1],0,... 'CoordinateSystem','uv',... 'Type','powerdb');```

Plot the 3-D magnitude pattern of a custom cardioid microphone with both the azimuth and elevation angles restricted to the range -40 to 40 degrees in 0.1 degree increments.

Create a custom microphone element with a cardioid pattern.

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

Plot the 3-D magnitude pattern.

```fc = 500; pattern(sCustMike,fc,[-40:0.1:40],[-40:0.1:40],... 'CoordinateSystem','polar',... 'Type','efield');```