raytrace

Display or compute RF propagation rays

Syntax

raytrace(tx,rx)

raytrace(tx,rx,propmodel)

raytrace(___,Name,Value)

rays = raytrace(___)

Description

The raytrace function plots or computes propagation paths by using ray tracing with surface geometry defined by the 'Map' property. Each plotted propagation path is color-coded according to the received power (dBm) or path loss (dB) along the path. The ray tracing analysis includes surface reflections but does not include effects from diffraction, refraction, or scattering. Operational frequency for this function is from 100 MHz to 100 GHz. For more information, see Choose a Propagation Model.

example

raytrace(tx,rx) displays the propagation paths from the transmitter site (tx) to the receiver site (rx) in the current Site Viewer by using the shooting and bouncing rays (SBR) method with up to two reflections.

example

raytrace(tx,rx,propmodel) displays 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) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes.

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

Examples

collapse all

Obstructed and Reflected Paths Using Ray Tracing

Open Live Script

Show reflected propagation paths in Chicago using the ray tracing analysis with the SBR method

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 and a receiver site near another building.

tx = txsite("Latitude",41.8800, ...
    "Longitude",-87.6295, ...
    "TransmitterFrequency",2.5e9);
show(tx)
rx = rxsite("Latitude",41.8813452, ...
    "Longitude",-87.629771, ...
    "AntennaHeight",30);
show(rx)

Show obstruction to line-of-sight.

los(tx,rx)

Show reflected propagation path using ray tracing with up to two reflections.

raytrace(tx,rx)

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

Signal Strength Using Ray Tracing Propagation Model

Open Live Script

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 SBR method, and performs line-of-sight and two-reflection analysis.

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

ssTwoReflections = -54.3015

Plot the propagation paths for SBR with up to two reflections.

raytrace(tx,rx,pm)

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

pm.MaxNumReflections = 5;
ssFiveReflections = sigstrength(rx,tx,pm)

ssFiveReflections = -53.3889

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

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

ssPerfect = -39.6703

Plot the propagation paths for SBR with up to five reflections.

raytrace(tx,rx,pm)

Appendix

Path Loss Due to Material Reflection and Atmosphere

Open Live Script

Calculate path loss due to material reflection and atmosphere in Hong Kong. Configure a ray tracing model to use the shooting and bouncing rays (SBR) method with up to 5 reflections.

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 with up to 5 reflections. Specify the ray tracing method as shooting and bouncing rays (SBR).

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

Visualize the propagation paths and compute the corresponding path losses.

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

plPerfect = 1×13

  104.2656  103.5720  112.0095  109.3152  111.2814  112.0011  112.4436  108.1516  111.2827  111.3898  117.7513  116.5894  117.7638

Recompute and visualize the propagation paths after configuring material reflection loss by setting building and terrain material types in 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×13

  104.2656  106.1294  119.2408  121.2477  122.4096  121.5561  126.9482  124.1615  122.8182  127.5476  139.0676  140.5833  153.3285

Recompute and visualize the propagation paths with atmospheric loss by adding atmospheric propagation models.

pm = pm + propagationModel("rain") + propagationModel("gas");
raytrace(tx,rx,pm,"Type","pathloss")
raysAtmospheric = raytrace(tx,rx,pm,"Type","pathloss");
plAtmospheric = [raysAtmospheric{1}.PathLoss]

plAtmospheric = 1×13

  105.3245  107.1891  121.8260  123.1432  124.9966  124.1453  129.6661  126.0578  125.4086  130.2655  143.0507  144.5666  157.3145

Appendix

Visualize Ray Tracing in Conference Room

Open Live Script

This example shows how to:

Scale an STL file so that the model uses units of meters.
View the scaled model in Site Viewer.
Use ray tracing to calculate and display propagation paths from a transmitter to a receiver.

While Cartesian txsite and rxsite objects require position coordinates in meters, STL files might use other units. If your STL file does not use meters, you must scale the model before importing it into Site Viewer.

Read an STL file as a triangulation object. The file models a small conference room with one table and four chairs.

TR = stlread("conferenceroom.stl");

Scale the coordinates and create a new triangulation object. For this example, assume that the conversion factor from the STL units to meters is 0.9.

scale = 0.9;
scaledPts = TR.Points * scale;
TR_scaled = triangulation(TR.ConnectivityList,scaledPts);

View the new triangulation object using Site Viewer. Alternatively, you can save the new triangulation object as an STL file by using the stlwrite function.

viewer = siteviewer("SceneModel",TR_scaled);

Create and display a transmitter site close to the wall and a receiver site under the table. Specify the position using Cartesian coordinates in meters.

tx = txsite("cartesian", ...
    "AntennaPosition",[-1.25; -1.25; 1.9], ...
    "TransmitterFrequency",2.8e9);
show(tx,"ShowAntennaHeight",false) 

rx = rxsite("cartesian", ...
    "AntennaPosition",[0.3; 0.2; 0.5]);
show(rx,"ShowAntennaHeight",false)

Pan by left-clicking, zoom by right-clicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and left-clicking and dragging.

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

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

Calculate the propagation paths and return the result as a comm.Ray object. Extract and plot the rays.

r = raytrace(tx,rx,pm);
r = r{1};
plot(r)

View information about a ray by clicking on it.

Input Arguments

collapse all

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

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

`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 is 'raytracing', a ray tracing propagation model that uses the SBR method with the maximum number of reflections set to 2.

To specify a ray tracing propagation model that calculates different numbers of reflections, create a RayTracing object by using the propagationModel function and set the MaxNumReflections property.

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.

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_{r x} = P_{t x} + G_{t x} + G_{r x} - L - L_{t x} - L_{r x}$

where:

P_rx is the received power along the path.
P_tx is the transmit power defined in tx.TransmitterPower.
G_tx is the antenna gain of tx in the direction of the angle-of-departure (AoD).
G_rx is the antenna gain of rx in the direction of the angle-of-arrival (AoA).
L is the path loss calculated along the path.
L_tx is the system loss of the transmitter defined in tx.SystemLoss.
L_rx 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 SBR method with up to 2 reflections for the ray tracing propagation model object configuration

To perform ray tracing analysis using the image method instead, specify a propagation model created using the propagationModel function. This code shows how to create a propagation model that uses the image method.

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

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

Data Types: char

`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

`Colormap` — Colormap for coloring propagation paths
`'jet'` (default) | predefined color map name | M-by-3 array of RGB

Colormap 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

`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 | `triangulation` object | string scalar | character vector

Map for visualization or surface data, specified as a siteviewer object, a triangulation object, a string scalar, or a character vector. Valid and default values depend on the coordinate system.

Coordinate System	Valid map values	Default map value
`"geographic"`	A `siteviewer` object^a. A terrain name, 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`.	The current `siteviewer` object or a new `siteviewer` object if none are open. `"gmted2010"`, if the function is called with an output.
`"cartesian"`	`"none"`. A `siteviewer` object. The name of an STL file. A `triangulation` object.	`"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

collapse all

`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. Within each row vector, the comm.Ray objects with the same transmitter to receiver interactions types are grouped together, groups are sorted alphabetically and then by ascending number of reflections. In each group, the rays are ordered by increasing propagation distance.

Version History

Introduced in R2019b

expand all

R2022b: SBR method finds paths with exact geometric accuracy

When you find propagation paths using the SBR method, MATLAB^® corrects the results so that the geometric accuracy of each path is exact, using single-precision floating-point computations. In previous releases, the paths have approximate geometric accuracy.

For example, this code finds propagation paths between a transmitter and receiver by using the default SBR method and returns the paths as comm.Ray objects. In R2022b, the raytrace function finds seven propagation paths. In earlier releases, the function approximates eight propagation paths, one of which is a duplicate path.

viewer = siteviewer(Buildings="hongkong.osm");
 
tx = txsite(Latitude=22.2789,Longitude=114.1625,AntennaHeight=10, ...
   TransmitterPower=5,TransmitterFrequency=28e9);
rx = rxsite(Latitude=22.2799,Longitude=114.1617,AntennaHeight=1);
 
rSBR = raytrace(tx,rx)
raytrace(tx,rx)

R2022b	R2022a
rSBR = 1×1 cell array {1×7 comm.Ray}	rSBR = 1×1 cell array {1×8 comm.Ray}

Paths calculated using the SBR method in R2022b more closely align with paths calculated using the image method. The image method finds all possible paths with exact geometric accuracy. For example, this code uses the image method to find propagation paths between the same transmitter and receiver.

viewer = siteviewer(Buildings="hongkong.osm");
 
tx = txsite(Latitude=22.2789,Longitude=114.1625, ...
   AntennaHeight=10,TransmitterPower=5, ...
   TransmitterFrequency=28e9);
rx = rxsite(Latitude=22.2799,Longitude=114.1617, ...
   AntennaHeight=1);
 
pm = propagationModel("raytracing",Method="image",MaxNumReflections=2);
 
rImage = raytrace(tx,rx,pm)

rImage =

  1×1 cell array

    {1×7 comm.Ray}

In this case, the SBR method finds the same number of propagation paths as the image method. In general, the SBR method finds a subset of the paths found by the image method. When both the image and SBR methods find the same path, the points along the path are the same within a tolerance of machine precision for single-precision floating-point values.

This code compares the path losses, within a tolerance of 0.0001, calculated by the SBR and image methods.

abs([rSBR{1}.PathLoss]-[rImage{1}.PathLoss]) < 0.0001

ans =

  1×7 logical array

   1   1   1   1   1   1   1

The path losses are the same within the specified tolerance.

As a result, the raytrace function can return different results in R2022b compared to previous releases.

The function can return a different number of comm.Ray objects because it discards invalid or duplicate paths.
The function can return different comm.Ray objects because it calculates exact paths rather than approximate paths.

R2022a: `NumReflections` name-value argument will be removed

The NumReflections name-value argument will be removed in a future release. The NumReflections name-value argument now only applies for the image ray tracing method. Instead, create a propagation model by using the propagationModel function with its MaxNumReflections name-value argument. Then, use the raytrace function with the propagation model as an input. This example shows the recommended workflow.

pm = propagationModel('raytracing', ...
    'Method','image','MaxNumReflections',2);
rays = raytrace(tx,rx,pm);

R2021b: `raytrace` function uses SBR method

Starting in R2021b, the raytrace function uses the shooting and bouncing rays (SBR) method and calculates up to two reflections by default. In previous releases, the raytrace function uses the image method and calculates up to one reflection.

To display or compute RF propagation rays using the image method instead, create a propagation model by using the propagationModel function. Then, use the raytrace function with the propagation model as input. This example shows how to update your code.

pm = propagationModel('raytracing','Method','image');
raytrace(tx,rx,pm)

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

Starting in R2021b, all RF Propagation functions use the SBR method by default and calculate up to two reflections. For more information, see Default modeling method is shooting and bouncing rays method.

raytrace

Syntax

Description

Examples

Obstructed and Reflected Paths Using Ray Tracing

Signal Strength Using Ray Tracing Propagation Model

Path Loss Due to Material Reflection and Atmosphere

Visualize Ray Tracing in Conference Room

Input Arguments

`tx` — Transmitter site
`txsite` object | array of `txsite` objects

`rx` — Receiver site
`rxsite` object | array of `rxsite` objects

`propmodel` — Propagation model
character vector | string | ray tracing propagation model created with `propagationModel`

Name-Value Arguments

`Type` — Type of quantity to plot
`'power'` (default) | `'pathloss'`

`PropagationModel` — Type of propagation model for ray tracing analysis
`'raytracing'` (default) | ray tracing propagation model created with `propagationModel`

`ColorLimits` — Color limits for colormap
two-element numeric row vector

`Colormap` — Colormap for coloring propagation paths
`'jet'` (default) | predefined color map name | M-by-3 array of RGB

`ShowLegend` — Show color legend on map
`true` (default) | `false`

`Map` — Map for visualization or surface data
`siteviewer` object | `triangulation` object | string scalar | character vector

Output Arguments

`rays` — Ray configuration object
M-by-N cell array

Version History

R2022b: SBR method finds paths with exact geometric accuracy

R2022a: `NumReflections` name-value argument will be removed

R2021b: `raytrace` function uses SBR method

See Also

Functions

Objects

Topics

raytrace

Syntax

Description

Examples

Obstructed and Reflected Paths Using Ray Tracing

Signal Strength Using Ray Tracing Propagation Model

Path Loss Due to Material Reflection and Atmosphere

Visualize Ray Tracing in Conference Room

Input Arguments

tx — Transmitter site txsite object | array of txsite objects

rx — Receiver site rxsite object | array of rxsite objects

propmodel — Propagation model character vector | string | ray tracing propagation model created with propagationModel

Name-Value Arguments

Type — Type of quantity to plot 'power' (default) | 'pathloss'

PropagationModel — Type of propagation model for ray tracing analysis 'raytracing' (default) | ray tracing propagation model created with propagationModel

ColorLimits — Color limits for colormap two-element numeric row vector

Colormap — Colormap for coloring propagation paths 'jet' (default) | predefined color map name | M-by-3 array of RGB

ShowLegend — Show color legend on map true (default) | false

Map — Map for visualization or surface data siteviewer object | triangulation object | string scalar | character vector

Output Arguments

rays — Ray configuration object M-by-N cell array

Version History

R2022b: SBR method finds paths with exact geometric accuracy

R2022a: NumReflections name-value argument will be removed

R2021b: raytrace function uses SBR method

See Also

Functions

Objects

Topics

`tx` — Transmitter site
`txsite` object | array of `txsite` objects

`rx` — Receiver site
`rxsite` object | array of `rxsite` objects

`propmodel` — Propagation model
character vector | string | ray tracing propagation model created with `propagationModel`

`Type` — Type of quantity to plot
`'power'` (default) | `'pathloss'`

`PropagationModel` — Type of propagation model for ray tracing analysis
`'raytracing'` (default) | ray tracing propagation model created with `propagationModel`

`ColorLimits` — Color limits for colormap
two-element numeric row vector

`Colormap` — Colormap for coloring propagation paths
`'jet'` (default) | predefined color map name | M-by-3 array of RGB

`ShowLegend` — Show color legend on map
`true` (default) | `false`

`Map` — Map for visualization or surface data
`siteviewer` object | `triangulation` object | string scalar | character vector

`rays` — Ray configuration object
M-by-N cell array

R2022a: `NumReflections` name-value argument will be removed

R2021b: `raytrace` function uses SBR method