raytrace

Plot propagation paths between sites

Description

example

raytrace(tx,rx) plots the propagation paths from the transmitter site (tx) to the receiver site (rx). The propagation paths are found using ray tracing with the terrain and buildings data defined in the Site Viewer map. Each propagation path is color-coded according to the received power (dBm) or path loss (dB) along the path.

Note

The ray tracing analysis includes surface reflections but does not include effects from refraction, diffraction, or scattering.

raytrace(tx,rx,propmodel) plots the propagation paths from the transmitter site (tx) to the receiver site (rx) based on the specified propagation model. To input building and terrain materials to calculate path loss, please use the 'raytracing-image-method' propagation model and set the properties to specify building materials.

raytrace(___,Name,Value) plots propagation paths with additional options specified by one or more name-value pairs.

rays = raytrace(___) returns the propagation paths in rays.

Examples

collapse all

Launch Site Viewer with buildings in Chicago.

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

Create transmitter site on a building.

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

Create receiver site near another building.

rx = rxsite('Latitude',41.881352, ...
    'Longitude',-87.629771, ...
    'AntennaHeight',30);

Compute signal strength using ray tracing propagation model and default single-reflection analysis.

pm = propagationModel("raytracing-image-method");
ssOneReflection = sigstrength(rx,tx,pm)
ssOneReflection = -55.2839

Compute signal strength with analysis up to two reflections, where total received power is the cumulative power of all propagation paths

pm.MaxNumReflections = 2;
ssTwoReflections = sigstrength(rx,tx,pm)
ssTwoReflections = -53.1827

Observe effect of material by replacing default concrete material with perfect reflector.

pm.BuildingsMaterial = 'perfect-reflector';
ssPerfect = sigstrength(rx,tx,pm)
ssPerfect = -42.0872

Plot propagation paths.

raytrace(tx, rx, pm) 

Launch Site Viewer with buildings in Hong Kong.

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

Define transmitter and receiver sites to model a small cell scenario in a dense urban environment.

tx = txsite("Name","Small cell transmitter", ...
       "Latitude",22.2789, ...
       "Longitude",114.1625, ...
       "AntennaHeight",10, ...
       "TransmitterPower",5, ...
       "TransmitterFrequency",28e9);
rx = rxsite("Name","Small cell receiver", ...
       "Latitude",22.2799, ...
       "Longitude",114.1617, ...
       "AntennaHeight",1);

Create ray tracing propagation model for perfect reflection.

pm = propagationModel("raytracing-image-method", ...
       "BuildingsMaterial","perfect-reflector", ...
       "TerrainMaterial","perfect-reflector");

Visualize propagation paths and compute corresponding path losses.

raytrace(tx,rx,pm,"Type","pathloss")
raysPerfect = raytrace(tx,rx,pm,"Type","pathloss");
plPerfect = [raysPerfect{1}.PathLoss]
plPerfect = 1×3

  104.2656  104.2745  112.0095

Re-compute with material reflection loss by setting material type on the propagation model. The first value is unchanged because it corresponds to the line-of-sight propagation path.

pm.BuildingsMaterial = "glass";
pm.TerrainMaterial = "concrete";
raytrace(tx,rx,pm,"Type","pathloss")
raysMtrls = raytrace(tx,rx,pm,"Type","pathloss");
plMtrls = [raysMtrls{1}.PathLoss]
plMtrls = 1×3

  104.2656  106.2547  146.5527

Input Arguments

collapse all

Receiver site, specified as a rxsite object or an array of rxsite objects. If the transmitter sites are specified as arrays, then the propagation paths are plotted from each transmitter to each receiver site.

Transmitter site, specified as a txsite object or an array of txsite objects. If the receiver sites are specified as arrays, then the propagation paths are plotted from each transmitter to each receiver site.

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 'raytracing-image-method'.

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 of quantity to plot, specified as the comma-separated pair consisting of 'Type' and 'power' in dBm or 'pathloss' in dB.

When you specify 'power', each path is color-coded according to the received power along the path. When you specify 'pathloss', each path is color-coded according to the path loss along the path.

Friis equation is used to calculate the received power:

Prx=Ptx+Gtx+GrxLLtxLrx

where:

  • Prx is the received power along the path.

  • Ptx is the transmit power defined in tx.TransmitterPower.

  • Gtx is the antenna gain of tx in the direction of the angle-of-departure (AoD).

  • Grx is the antenna gain of rx in the direction of the angle-of-arrival (AoA).

  • L is the path loss calculated along the path.

  • Ltx is the system loss of the transmitter defined in tx.SystemLoss.

  • Lrx is the system loss of the receiver defined in rx.SystemLoss.

Data Types: char

Type of propagation model for ray tracing analysis, specified as the comma-separated pair consisting of 'PropagationModel' and 'raytracing-image-method' or a ray tracing propagation model object created using propagationModel.

Data Types: char

Number of reflections to search for in propagation paths using ray tracing, specified as the comma-separated pair consisting of 'NumReflections' and a numeric row vector whose elements are 0, 1, or 2.

The default value results in the search for a line-of-sight propagation path along with propagation paths that each contain a single reflection.

Data Types: double

Color map for coloring propagation paths, specified as the comma-separated pair consisting of 'Colormap' and a predefined color map name or an M-by-3 array of RGB (red, blue, green) triplets that define M individual colors.

Data Types: char | double

Color limits for colormap, specified as the comma-separated pair consisting of 'ColorLimits' and a two-element numeric row vector of the form [min max]. The units and default values of the color limits depend on the value of the 'Type' parameter:

  • 'power'– Units are in dBm, and the default value is [-120 -5].

  • 'pathloss'– Units are in dB, and the default value is [45 160].

The color limits indicate the values that map to the first and last colors in the colormap. Propagation paths with values below the minimum color limit are not plotted.

Data Types: double

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

Data Types: logical

Map for visualization and surface data, specified as a siteviewer object. The default value is the current Site Viewer.

Data Types: char | string

Output Arguments

collapse all

Ray configuration, returned as a M-by-N cell array where M is the number of transmitter sites and N is the number of receiver sites. Each cell element is a row vector of objects representing all the rays found between the corresponding transmitter site and receiver site. array. Within each row vector, the comm.Ray objects are ordered by increasing number of reflections, and where number of reflections are equal they are ordered by increasing propagation distance.

See Also

|

Introduced in R2019b