patternFromAI

R2026b

Reconstruct 3-D radiation pattern of antenna or array using AI

Since R2024a

Syntax

patternFromAI(magVertSlice, angleVertSlice, magHorizSlice, angleHorizSlice)

[p3D, vertAngleOut, horizAngleOut] = patternFromAI(___)

p3D = patternFromAI(data, angle1, angle2)

[p3D, vertAngleOut, horizAngleOut] = patternFromAI(data, angle1, angle2)

[___] = patternFromAI(___,Name=Value)

Description

Note

To use the patternFromAI function, you need a Deep Learning Toolbox™ license in addition to the Antenna Toolbox™ license.

To reconstruct a pattern from sparse input data, or to specify the NumSteps name-value argument, you must also download and install the Machine Learning Models for Antenna Toolbox support package. You can also interactively install the support package using the Add-Ons panel. Reconstruction from two orthogonal slices does not require the support package.

patternFromAI(magVertSlice, angleVertSlice, magHorizSlice, angleHorizSlice) plots the approximate 3-D radiation pattern reconstructed from the magnitude and angle data of input orthogonal slices vertslice and horizSlice.

[p3D, vertAngleOut, horizAngleOut] = patternFromAI(___) returns the reconstructed pattern as a matrix along with the vectors of the horizontal and vertical angle values in degrees. For the matrix p3D, the number of rows/columns correspond to the number of elements of horizAngleOut/vertAngleOut.

p3D = patternFromAI(data, angle1, angle2) reconstructs the 3-D radiation pattern from sparse magnitude samples data specified at the sample angles angle1 and angle2, and returns the pattern as the matrix p3D. Use this syntax to reconstruct a pattern from irregularly sampled data instead of two orthogonal slices.

This syntax requires the Machine Learning Models for Antenna Toolbox support package.

[p3D, vertAngleOut, horizAngleOut] = patternFromAI(data, angle1, angle2) also returns the vectors of vertical and horizontal angle values in degrees.

This syntax requires the Machine Learning Models for Antenna Toolbox support package.

[___] = patternFromAI(___,Name=Value) specifies customization and tuning options, such as the angle convention, additional minimum and maximum magnitudes for slice normalization, and pattern plot options using one or more name-value arguments.

Examples

Reconstruct 3-D Radiation Pattern of Dipole from 2-D Orthogonal Slices

This example shows how to reconstruct the 3-D radiation pattern of a dipole antenna operating at 70 MHz from its two orthogonal slices.

Get 2-D Pattern Data of Dipole Antenna

Define the azimuth and elevation angle ranges. Get the azimuth pattern data at $0^{\circ }$ elevation. Visualize the azimuth pattern.

az = 0:359;
el = -180:179;
pA = patternAzimuth(dipole,70e6,0,Azimuth=az);
figure
patternAzimuth(dipole,70e6,0,Azimuth=az)

Get the elevation pattern data at $0^{\circ }$ azimuth. Visualize the elevation pattern.

pE = patternElevation(dipole,70e6,0,Elevation=el);
figure
patternElevation(dipole,70e6,0,Elevation=el)

Reconstruct 3-D Radiation Pattern of Dipole Antenna

Use patternFromAI function to reconstruct the 3-D radiation pattern. Visualize the 3-D pattern.

theta = 90-el;
phi = az;
[p3D, vertAngleOut, horizAngleOut] = patternFromAI(pE,theta,pA,phi);
figure
patternFromAI(pE,theta,pA,phi)

Reconstruct 3-D Radiation Pattern from Imported 2-D Pattern Data

This example shows how to import 2-D pattern data from a .pln file and reconstruct the 3-D radiation pattern from it.

Import 2-D Pattern Data

Use the msiread function to read a .pln file and import its contents to the workspace. Extract the magnitude and angles data form the workspace variables.

[Horizontal,Vertical] = msiread('Test_file_demo.pln');
pE = Vertical.Magnitude;
el = Vertical.Elevation;
pA = Horizontal.Magnitude;
az = Horizontal.Azimuth;

Plot the elevation cut.

figure 
polarpattern(Vertical.Elevation,Vertical.Magnitude,TitleTop="Elevation Cut")

Plot the azimuth cut.

figure 
polarpattern(Horizontal.Azimuth,Horizontal.Magnitude,TitleTop="Azimuthal Cut")

Reconstruct 3-D Pattern

Use the "az-el" angle convention to reconstruct the 3-D pattern from imported 2-D pattern magnitude and angle data.

figure
patternFromAI(pE,el,pA,az,AngleConvention="az-el")

Input Arguments

magVertSlice — 2-D pattern slice magnitude data along vertical/elevation plane in dBi

1-by-360 real vector | 1-by-361 real vector

2-D pattern slice magnitude data along vertical/elevation plane in dBi, specified as a real-valued vector of either 360 or 361 elements, sampled at 1 degree resolution.

Example: [10.55 10.25 10 ... -2]

Data Types: double

angleVertSlice — Vertical/elevation slice angles in degrees

1-by-360 real integer vector | 1-by-361 real integer vector

Vertical/elevation slice angles in degrees, specified as a real-valued integer vector of either 360 or 361 elements, at 1 degree spacing.

Example: 0:360

Data Types: double

magHorizSlice — 2-D pattern slice magnitude data along horizontal/azimuth plane in dBi

1-by-360 real vector | 1-by-361 real vector

2-D pattern slice magnitude data along horizontal/azimuth plane in dBi, specified as a real-valued vector of either 360 or 361 elements, sampled at 1 degree resolution.

Example: [10.55 10.25 10 ... -2]

Data Types: double

angleHorizSlice — Horizontal/azimuth slice angles in degrees

1-by-360 real integer vector | 1-by-361 real integer vector

Horizontal/azimuth slice angles in degrees, specified as a real-valued integer vector of either 360 or 361 elements, at 1 degree spacing.

Example: 0:360

Data Types: double

data — Sparse pattern magnitude samples in dBi

N-element real vector

Sparse pattern magnitude samples in dBi, specified as a real-valued vector. Each element is the directivity, in dBi, at the corresponding sample angles specified by angle1 and angle2. The vectors data, angle1, and angle2 must have the same number of elements. Use this argument to reconstruct a pattern from irregularly sampled data instead of two orthogonal slices.

Example: [10.55 10.25 10 ... -2]

Dependencies

To reconstruct a pattern from sparse input data, you must download and install the Machine Learning Models for Antenna Toolbox support package.

Data Types: double

angle1 — First angle coordinate of sparse samples in degrees

N-element real vector

First angle coordinate of the sparse samples in degrees, specified as a real-valued vector with the same number of elements as data. The interpretation of angle1 depends on the AngleConvention name-value argument: it is the φ (phi) angle when AngleConvention is "phi-theta", and the azimuth angle when AngleConvention is "az-el".

Example: [0 30 45 90 ... 360]

Data Types: double

angle2 — Second angle coordinate of sparse samples in degrees

N-element real vector

Second angle coordinate of the sparse samples in degrees, specified as a real-valued vector with the same number of elements as data. The interpretation of angle2 depends on the AngleConvention name-value argument: it is the θ (theta) angle when AngleConvention is "phi-theta", and the elevation angle when AngleConvention is "az-el".

Example: [90 90 60 30 ... 0]

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.

Example: AngleConvention="az-el"

AngleConvention — Angle convention used in input angles

"phi-theta" (default) | "az-el"

Angle convention used in the input angles vertAngle and horizAngle for reconstruction, specified as either "phi-theta" or "az-el". The default angle convention is "phi-theta". For more information on angle conventions, see Antenna Toolbox Coordinate System.

Example: "az-el"

Data Types: string

MinMaxMagnitude — Magnitudes to normalize slice data

[min max] of slice data (default) | 2-element vector

Magnitudes to normalize the input data, specified as a 2-element vector in dBi. The first element of the vector is the minimum magnitude and second element is the maximum magnitude. To specify only one element, assign the other as -Inf or Inf respectively.

When you use the Machine Learning Models for Antenna Toolbox support package, the default is the model-trained normalization window [peak-60 peak], where peak is the maximum magnitude in the input data. In this case, Inf resolves to the observed maximum and -Inf resolves to 60 dB below the resolved maximum. For example, [-Inf 25] resolves to [-35 25], and [-Inf Inf] is equivalent to the default window.

When the support package is not installed, patternFromAI uses the literal minimum and maximum values in the input slices, and finite values override the corresponding bound directly.

Tip

If the minimum and/or maximum directivity values of the pattern are known but are absent from the input data, specify either one or both in the MinMaxMagnitude argument to increase the accuracy of the pattern reconstruction.

Example: [10 50]

Data Types: double

PatternOptions — Plot visualization options

PatternPlotOptions object (default)

Plot visualization options, specified as a PatternPlotOptions object. Only the Transparency and MagnitudeScale properties of PatternPlotOPtions can be changed. The other two properties SizeRatio and AntennaOffset are ignored.

Example: PatternPlotOptions(Transparency=0.6, MagnitudeScale=[1 10])

NumSteps — Number of reverse diffusion steps

25 (default) | positive integer in the range [1, 1000]

Number of reverse diffusion steps used during reconstruction, specified as a positive integer in the range [1, 1000]. A larger value of NumSteps can improve reconstruction quality at the cost of longer computation time.

Example: 50

Dependencies

This name-value argument requires the Machine Learning Models for Antenna Toolbox support package.

Data Types: double

MaxDegree — Maximum spherical harmonic degree for angular smoothing

[] (default) | positive integer in the range [1, 90]

Maximum spherical harmonic degree for angular smoothing, specified as a positive integer in the range [1, 90]. This argument applies an angular low-pass operation by truncating the spherical harmonic expansion of the reconstructed pattern to degree MaxDegree. A smaller value produces smoother, more global angular structure, and a larger value preserves sharper lobes, narrower nulls, and finer angular detail. Use a smaller value to suppress small-scale artifacts or noise, and a larger value to preserve localized angular features. If you do not specify MaxDegree, the function does not apply angular smoothing and preserves all angular content that the output grid can represent.

The output grid must be able to represent the requested degree, so both output angular dimensions must support at least 2*MaxDegree + 1 samples. If the requested degree is not supported by the output grid, patternFromAI clamps the degree to the largest supported value and issues a warning.

Example: 20

Data Types: double

Tilt — Rotation angle of reconstructed pattern in degrees

[] (default) | real scalar | real vector

Rotation angle of the reconstructed pattern in degrees, specified as a real scalar or a real vector. The pattern is rotated on the sphere about the axis specified by the TiltAxis name-value argument. When you specify a vector, the rotations are applied in sequence. Rotation alone does not apply angular smoothing and preserves all angular content the output grid can represent. When you specify both Tilt and MaxDegree, the pattern is smoothed to the requested degree and then rotated in spherical harmonic coefficient space. If you do not specify Tilt, the function does not rotate the reconstructed pattern.

Example: 30

Data Types: double

TiltAxis — Axis of rotation for reconstructed pattern

"Z" (default) | "X" | "Y" | three-element vector

Axis of rotation for the reconstructed pattern, specified as "X", "Y", "Z", or a three-element vector [x y z] that defines the axis direction. When you specify Tilt as a vector, specify TiltAxis as a matrix with one axis per row, matching the number of tilt angles. Use this argument together with the Tilt name-value argument. When you specify Tilt but not TiltAxis, the function rotates the pattern about the z-axis. This argument has no effect if you do not specify Tilt.

Example: "Y"

Data Types: string | double

Output Arguments

p3D — 3-D pattern magnitude data in dBi

360-by-181 real matrix

3-D pattern magnitude data in dBi, returned as a 360-by-181 real matrix on an equiangular grid with no duplicated azimuth (φ) seam. The number of rows equals the number of elements of horizAngleOut, and the number of columns equals the number of elements of vertAngleOut.

Data Types: double

vertAngleOut — Vertical or elevation angles in degrees

181-by-1 real integer vector

Vertical or elevation angles in degrees, returned as a 181-by-1 real integer vector. When AngleConvention is "phi-theta", the angles are the θ (theta) values returned in descending order from 180 to 0. When AngleConvention is "az-el", the angles are the corresponding elevation values.

Data Types: double

horizAngleOut — Horizontal or azimuth angles in degrees

360-by-1 real integer vector

Horizontal or azimuth angles in degrees, returned as a 360-by-1 real integer vector. When AngleConvention is "phi-theta", the angles are the φ (phi) values from 0 to 359. When AngleConvention is "az-el", the angles are the corresponding azimuth values.

Data Types: double

Version History

Introduced in R2024a

R2026b: Reconstruct patterns from sparse data and rotate reconstructed patterns

You can now reconstruct a full 3-D radiation pattern from sparse input data with irregular angular sampling, instead of from two orthogonal slices, by using the data, angle1, and angle2 input arguments. Reconstruction from sparse data, and the NumSteps name-value argument, require the Machine Learning Models for Antenna Toolbox support package.

You can also smooth and rotate the reconstructed pattern with any syntax by using the MaxDegree, Tilt, and TiltAxis name-value arguments. These arguments do not require the support package.

R2026b: Output pattern returned without duplicated azimuth seam

The patternFromAI function now returns the 3-D pattern p3D as a 360-by-181 real matrix on an equiangular grid, and the azimuth angles horizAngleOut as a 360-by-1 real vector, where the azimuth (φ) angles span 0 to 359 degrees with no duplicated seam. In previous releases, p3D was a 361-by-181 real matrix and horizAngleOut was a 361-by-1 real vector, in which the azimuth angles spanned 0 to 360 degrees and the pattern values at 0 and 360 degrees were duplicated. The vertical angles vertAngleOut remain a 181-by-1 real vector.

This change applies to all syntaxes, including reconstruction from two orthogonal slices. If your code depends on the previous 361-by-181 output, append the first azimuth row to recreate the duplicated seam. For example, if p3D and horizAngleOut are the returned pattern and azimuth angles, use p3D(end+1,:) = p3D(1,:) and horizAngleOut(end+1) = 360 to restore the previous sizes.