coverage

Display coverage map

Syntax

coverage(txs)

coverage(txs,propmodel)

coverage(txs,rxs)

coverage(txs,rxs,propmodel)

coverage(___,Name,Value,___)

pd = coverage(txs,___)

Description

coverage(txs) displays the coverage map for the transmitter site. Each colored contour of the map defines an area where the corresponding signal strength is transmitted to the mobile receiver.

Note

This function only supports antenna sites with CoordinateSystem property set to 'geographic'.

coverage(txs,propmodel) displays the coverage map based on the specified propagation model. The default propagation model is 'longley-rice' when terrain is in use and 'freespace' when terrain is not used.

coverage(txs,rxs) displays the coverage map based on the receiver site properties.

coverage(txs,rxs,propmodel) displays the coverage map based on the receiver site properties and specified propagation model.

coverage(___,Name,Value,___) displays the coverage map using additional options specified by the Name,Value pairs.

pd = coverage(txs,___) returns computed coverage data in the propagation data object, pd. No plot is displayed and any graphical only name-value pairs are ignored.

Examples

Coverage Map of Transmitter

Create a transmitter site at MathWorks headquarters.

tx = txsite('Name','MathWorks', ...
        'Latitude', 42.3001, ...
        'Longitude', -71.3503);

Show the coverage map.

coverage(tx)

Coverage Map Using Transmitter and Receiver

Create a transmitter site at MathWorks headquarters.

tx = txsite('Name','MathWorks', ...
        'Latitude', 42.3001, ...
        'Longitude', -71.3503);

Create a receiver site at Fenway Park with an antenna height of 1.2 m and system loss of 10 dB.

rx = rxsite('Name','Fenway Park', ...
       'Latitude',42.3467, ...
       'Longitude',-71.0972,'AntennaHeight',1.2,'SystemLoss',10);

Calculate the coverage area of the transmitter using a close-in propagation model.

coverage(tx,rx,'PropagationModel','closein')

Coverage Map for Strong and Weak Signals

Define strong and weak signal strengths with corresponding colors.

strongSignal = -75;
strongSignalColor = "green";
weakSignal = -90;
weakSignalColor = "cyan";

Create a transmitter site and display the coverage map.

tx = txsite('Name','MathWorks','Latitude', 42.3001,'Longitude', -71.3503);
coverage(tx,'SignalStrengths',[strongSignal,weakSignal], ...
       'Colors', [strongSignalColor,weakSignalColor])

Coverage Map of Directional Antenna in Rain

Define a Yagi-Uda antenna designed for a transmitter frequency of 4.5 GHz. Tilt the antenna to direct radiation in the XY-plane (i.e., geographic azimuth).

fq = 4.5e9;
y = design(yagiUda,fq);
y.Tilt = 90;
y.TiltAxis = 'y';

Create a transmitter site with this directional antenna.

tx = txsite('Name','MathWorks', ...
    'Latitude',42.3001,'Longitude',-71.3503, ...
    'Antenna',y,'AntennaHeight',60, ...
    'TransmitterFrequency',fq,'TransmitterPower',10);

Display the coverage map using the rain propagation model. The map pattern points east, which corresponds to default antenna angle value of 0 degrees.

coverage(tx,'rain','SignalStrengths',-90)

Combined Coverage Map of Multiple Transmitters

Define the names and the locations of sites around Boston.

names = ["Fenway Park","Faneuil Hall","Bunker Hill Monument"];
lats = [42.3467,42.3598,42.3763];
lons = [-71.0972,-71.0545,-71.0611];

Create the transmitter site array.

txs = txsite('Name', names,...
       'Latitude',lats,...
       'Longitude',lons, ...
       'TransmitterFrequency',2.5e9);

Display the combined coverage map for multiple signal strengths, using close-in propagation model.

coverage(txs,'close-in','SignalStrengths',-100:5:-60)

Coverage Map Using Longley-Rice and Ray Tracing Method

Launch Site Viewer using buildings in Chicago. For more information about the osm file, see [1].

viewer = siteviewer("Buildings","chicago.osm");

Create a transmitter site on the building.

tx = txsite('Latitude',41.8800, ...
   'Longitude',-87.6295, ...
   'TransmitterFrequency',2.5e9);
show(tx)

Coverage Map Using Longley-Rice Propagation Model

Create a coverage map of the city using the Longley-Rice propagation model.

coverage(tx,"SignalStrengths",-100:-5,"MaxRange",250,"Resolution",1)

Longley-Rice models over-the-rooftops propagation along vertical slices and obstructions tend to dominate the coverage region.

Coverage Map Using Ray Tracing Propagation Model and Image Method

Create a coverage map of the city using a ray tracing propagation model. By default, the ray tracing propagation model uses the image method and the coverage region includes line-of-sight and single-reflection propagation paths.

coverage(tx,"raytracing","SignalStrengths",-100:-5, ...
    "MaxRange",250,"Resolution",2)

This coverage map shows new regions that are in service due to reflected propagation paths.

Coverage Map Using Ray Tracing Propagation Model and SBR Method

Create a coverage map of the city using a ray tracing propagation model. Specify the ray tracing method as shooting and bouncing rays (SBR). The SBR method is generally faster than the image method. Increase the maximum number of path reflections to 2.

pm = propagationModel("raytracing","Method","sbr", ...
    "MaxNumReflections",2);
coverage(tx,pm,"SignalStrengths",-100:-5, ...
    "MaxRange",250,"Resolution",2)

This coverage map shows new regions that are in service due to the additional reflected propagation paths.

Appendix

[1] The osm file is downloaded from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Input Arguments

txs — Transmitter sites

txsite object | array of txsite objects

Transmitter site, specified as a txsite object. Use array inputs to specify multiple sites.

This function only supports plotting antenna sites when CoordinateSystem property is set to 'geographic'.

rxs — Receiver sites

rxsite object | array of rxsite objects

Receiver site, specified as a rxsite object. Use array inputs to specify multiple sites.

This function only supports plotting antenna sites when CoordinateSystem property is set to 'geographic'.

propmodel — Propagation model

character vector | string

Propagation model, specified as a character vector or string. You can also use the name-value pair 'PropagationModel' to specify this parameter. You can also use the propagationModel function to define this input. The default propagation model is 'longley-rice' when terrain is enabled and 'freespace' when terrain is disabled.

Data Types: char | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Type','power'

'Type' — Type of signal strength to compute

'power' (default) | 'efield'

Type of signal strength to compute, specified as the comma-separated pair consisting of 'Type' and 'power' or 'efield'.

When type is 'power', SignalStrengths is expressed in power units (dBm) of the signal at the mobile receiver input. When type is 'efield', SignalStrengths is expressed in electric field strength units (dBμV/m) of signal wave incident on the antenna.

Data Types: char

'SignalStrengths' — Signal strengths to display on coverage map

numeric vector

Signal strengths to display on coverage map, specified as the comma-separated pair consisting of 'SignalStrengths' and a numeric vector.

Each strength uses different colored filled contour on the map. The default value is -100 dBm if the 'Type' name-value pair is 'power' and 40 dBμV/m if 'Type' is 'efield'.

Data Types: double

'PropagationModel' — Propagation model to use for path loss calculations

'longley-rice' (default) | 'freespace' | 'close-in' | 'rain' | 'gas' | 'fog' | 'raytracing' | propagation model created with propagationModel

Propagation model to use for the path loss calculations, specified as the comma-separated pair consisting of 'PropagationModel' and one of the following:

• 'freespace' — Free space propagation model

• 'rain' — Rain propagation model

• 'gas' — Gas propagation model

• 'fog' — Fog propagation model

• 'close-in' — Close-in propagation model

• 'longley-rice' — Longley-Rice propagation model

• 'tirem' — Tirem propagation model

• 'raytracing' — Ray tracing propagation model that uses the image method

• A propagation model created with the propagationModel function

The default propagation model is 'longley-rice' when terrain is enabled and 'freespace' when terrain is disabled.

Data Types: char

'MaxRange' — Maximum range of coverage map from each transmitter site

numeric scalar

Maximum range of coverage map from each transmitter site, specified as a positive numeric scalar in meters representing great circle distance. MaxRange defines the region of interest on the map to plot. The default value is automatically computed based on the type of propagation model.

Type of Propagation Model	MaxRange
Atmospheric or empirical	Range of minimum value in SignalStrengths.
Terrain	30 km or distance to the furthest building.
Ray tracing	500 m

For more information about the types of propagation models, see Choose a Propagation Model.

Data Types: double

'Resolution' — Resolution of coverage map

'auto' (default) | numeric scalar

Resolution of coverage map, specified as the comma-separated pair consisting of 'Resolution' and a numeric scalar in meters.

The resolution of 'auto' computes the maximum value scaled to 'MaxRange'. Decreasing the resolution increases the quality of the coverage map and the time required to create it.

Data Types: char | double

'ReceiverGain' — Mobile receiver gain

2.1 (default) | numeric scalar

Mobile receiver gain, specified as the comma-separated pair consisting of 'ReceiverGain' and a numeric scalar in dB. The receiver gain value includes the mobile receiver antenna gain and system loss.

The receiver gain computes received signal strength when the 'Type' is 'power'.

If receiver site argument rx is passed to coverage, the default value is the maximum gain of the receiver antenna with the system loss subtracted. Otherwise the default value is 2.1.

Data Types: char | double

'ReceiverAntennaHeight' — Mobile receiver antenna height above ground elevation

1 (default) | numeric scalar

Mobile receiver antenna height above ground elevation, specified as the comma-separated pair consisting of 'ReceiverAntennaHeight' and a numeric scalar in meters.

If receiver site argument rx is passed to coverage, the default value is the AntennaHeight of the receiver. Otherwise the default value is 1.

Data Types: double

'Colors' — Colors of filled contours on coverage map

M-by-3 array of RGB triplets | array of strings | cell array of character vectors

Filled contours color of coverage map, specified as the comma-separated pair consisting of 'Colors' and an M-by-3 array of RGB triplets, an array of strings, or a cell array of character vectors.

Colors are assigned element-wise to 'SignalStrengths' values for coloring the corresponding filled contours.

'Colors' cannot be used with 'ColorLimits' or 'ColorMap'.

For more information, see ColorSpec (Color Specification).

Data Types: char | string | double

'ColorLimits' — Color limits for colormap

two-element vector

Color limits for colormap, specified as the comma-separated pair consisting of 'ColorLimits' and a two-element vector of type [min max].

The color limits indicate the signal level values that map to the first and last colors on the colormap.

The default value is [-120 -5] if the 'Type' name-value pair is 'power' and [20 135] if 'Type' is 'efields'.

'ColorLimits' cannot be used with 'Color'.

Data Types: double

'ColorMap' — Colormap filled contours for coverage map

'jet' (default) | predefined color map | M-by-3 array of RGB triplets

Colormap filled contours on coverage map, specified as the comma-separated pair consisting of 'ColorMap' and a predefined colormap or M-by-3 array of RGB triplets, where M defines individual colors.

'ColorMap' cannot be used with 'Colors'.

Data Types: char | double

'ShowLegend' — Show signal strength color legend on map

true (default) | false

Show signal strength color legend on map, specified as the comma-separated pair consisting of 'ShowLegend' and true or false.

Data Types: logical

'Transparency' — Transparency of coverage map

0.4 (default) | numeric scalar

Transparency of coverage map, specified as the comma-separated pair consisting of 'Transparency' and a numeric scalar in the range 0 to 1. 0 is transparent and 1 is opaque.

Data Types: double

'Map' — Map for visualization of surface data

siteviewer object

Map for visualization of surface data, specified as the comma-separated pair consisting of 'Map' and a siteviewer object.^[1]

Data Types: char | string

Output Arguments

pd — Coverage data

propagationData object

Coverage data, returned as a propagationData object consisting of Latitude and Longitude, and a signal strength variable corresponding to the plot type. Name of the propagationData is "Coverage Data".