raytrace

Plot or compute propagation paths between sites

Syntax

raytrace(tx,rx)

raytrace(tx,rx,propmodel)

raytrace(___,Name,Value)

rays = raytrace(___)

Description

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 surface geometry defined by the Map property. Each propagation path is color-coded according to the received power (dBm) or path loss (dB) along the path, assuming unpolarized rays.

Note

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

• Operational frequency for this function is from 100 MHz to 100 GHz.

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, create a 'raytracing' propagation model using the propagationModel function 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

Signal Strength Using Ray Tracing Propagation Model

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

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

Create a transmitter site on a building.

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

Create a receiver site near another building.

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

Compute the signal strength by using a ray tracing propagation model. By default, the ray tracing model uses the image method and performs line-of-sight and single-reflection analysis.

pm = propagationModel("raytracing");
ssOneReflection = sigstrength(rx,tx,pm)

ssOneReflection = -54.0915

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 = -52.3890

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

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

ssPerfect = -41.9927

Plot the propagation paths.

raytrace(tx, rx, pm) 

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

Path Loss Due to Material Reflection and Atmosphere

Launch Site Viewer with buildings in Hong Kong. For more information about the osm file, see [1].

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 a ray tracing propagation model for perfect reflection. Specify the ray tracing method as shooting and bouncing rays (SBR).

pm = propagationModel("raytracing", ...
    "Method","sbr", ...
    "BuildingsMaterial","perfect-reflector", ...
    "TerrainMaterial","perfect-reflector");

Visualize the 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.2744  112.0094

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.2236  119.3577

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

Ray Tracing In Conference Room

Define a 3-D map for a conference room with one table and four chairs.

mapFileName = "conferenceroom.stl";

Visualize the 3-D map.

figure; view(3);
trisurf(stlread(mapFileName), 'FaceAlpha', 0.3, 'EdgeColor', 'none'); 
hold on; axis equal; grid off;
xlabel('x'); ylabel('y'); zlabel('z');

Define a transmitter site close to the wall and a receiver site under the table.

    tx = txsite("cartesian",  "AntennaPosition", [-1.45; -1.45; 1.5],"TransmitterFrequency", 2.8e9);
    rx = rxsite("cartesian","AntennaPosition", [.3; .2; .5]);

Plot the transmitter site in red and receiver site in blue.

scatter3(tx.AntennaPosition(1,:), tx.AntennaPosition(2,:), tx.AntennaPosition(3,:), 'sr', 'filled');
scatter3(rx.AntennaPosition(1,:), rx.AntennaPosition(2,:),rx.AntennaPosition(3,:), 'sb', 'filled');

Create a ray tracing propagation model for Cartesian coordinates. Specify the ray tracing method as shooting and bouncing rays (SBR). Set the surface material to wood.

pm = propagationModel("raytracing","CoordinateSystem","cartesian", ...
    "Method","sbr","MaxNumReflections",2,"SurfaceMaterial","wood"); 

Perform ray tracing and save the computed rays using comm.Ray object

rays = raytrace(tx, rx, pm, 'Map', mapFileName); 
rays = rays{1};

Visualize rays in the 3D map.

for i = 1:length(rays)
    if rays(i).LineOfSight
        propPath = [rays(i).TransmitterLocation, ...
                    rays(i).ReceiverLocation];
    else
        propPath = [rays(i).TransmitterLocation, ...
                rays(i).ReflectionLocations, ...
                    rays(i).ReceiverLocation];
    end
  
    line(propPath(1,:), propPath(2,:), propPath(3,:), 'Color', 'cyan');
end

Input Arguments

rx — Receiver site

rxsite object | array of rxsite objects

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.

tx — Transmitter site

txsite object | array of txsite objects

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.

propmodel — Propagation model

character vector | string | ray tracing propagation model created with propagationModel

Propagation model, specified as a character vector, a string, or a ray tracing propagation model created with the propagationModel function. The default propagation model is 'raytracing', a ray tracing propagation model that uses the image method.

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 quantity to plot

'power' (default) | 'pathloss'

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:

$$P_{rx}=P_{tx}+G_{tx}+G_{rx}-L-L_{tx}-L_{rx}$$

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

'PropagationModel' — Type of propagation model for ray tracing analysis

'raytracing' (default) | ray tracing propagation model created with propagationModel

Type of propagation model for ray tracing analysis, specified as the comma-separated pair consisting of 'PropagationModel' and 'raytracing' or a ray tracing propagation model created with the propagationModel function. If you specify 'raytracing', then the raytrace function calculates propagation paths by using the image method.

To perform ray tracing analysis using the shooting and bouncing rays (SBR) method instead, specify a propagation model created using the propagationModel function. This code shows how to create a propagation model that uses the SBR method.

pm = propagationModel('raytracing','Method','sbr');

For information about differences between the image and SBR methods, see Choose a Propagation Model.

Data Types: char

'NumReflections' — Number of reflections to search for in propagation paths

[0 1] (default) | numeric row vector

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 line-of-sight propagation paths and single-reflection propagation paths.

This argument is only supported for ray tracing propagation models that use the image method. For ray tracing propagation models that use the SBR method, specify the MaxNumReflections property of the propagation model instead. For more information, see the propagationModel function.

Data Types: double

'Colormap' — Color map for coloring propagation paths

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

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

'ColorLimits' — Color limits for colormap

two-element numeric row vector

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

'ShowLegend' — Show color legend on map

true (default) | false

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

Data Types: logical

'Map' — Map for visualization or surface data

siteviewer object | terrain name

Map for visualization or surface data, specified as the comma-separated pair consisting of 'Map and one of the following depending on the coordinate system:

Coordinate System	Valid map values	Default map value
'geographic'	siteviewer[a] A terrain name may be specified if the function is called with an output argument. Valid terrain names are 'none', 'gmted2010', or the name of the custom terrain data added using addCustomTerrain	current siteviewer or new siteviewer if none are open. 'gmted2010' if called with an output.
'cartesian'	'none', triangulation object or name of an STL file.	'none'
[a] Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

Data Types: char | string

Output Arguments

rays — Ray configuration object

M-by-N cell array

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 comm.Ray 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.