raytrace
Display or compute RF propagation rays
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 colorcoded 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.
raytrace(
displays the propagation paths from the transmitter site (tx
,rx
,propmodel
)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(___,
specifies options using one or more namevalue arguments in addition to the input
arguments in previous syntaxes.Name,Value
)
returns
the propagation paths in rays
= raytrace(___)rays
.
Examples
Obstructed and Reflected Paths Using Ray Tracing
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 lineofsight.
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 crowdsourced 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
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 lineofsight and tworeflection 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 = "perfectreflector";
ssPerfect = sigstrength(rx,tx,pm)
ssPerfect = 39.6703
Plot the propagation paths for SBR with up to five reflections.
raytrace(tx,rx,pm)
Appendix
[1] The osm file is downloaded from https://www.openstreetmap.org, which provides access to crowdsourced 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
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","perfectreflector", ... "TerrainMaterial","perfectreflector");
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 lineofsight 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
[1] The osm file is downloaded from https://www.openstreetmap.org, which provides access to crowdsourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.
Visualize Ray Tracing in Conference Room
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 leftclicking, zoom by rightclicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and leftclicking 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
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.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue 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 commaseparated pair
consisting of 'Type'
and 'power'
in dBm or 'pathloss'
in dB.
When you specify 'power'
, each path is colorcoded
according to the received power along the path. When you specify
'pathloss'
, each path is colorcoded 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:
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 angleofdeparture (AoD).G_{rx}
is the antenna gain of rx in the direction of the angleofarrival (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
commaseparated 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
twoelement numeric row vector
Color limits for colormap, specified as the commaseparated pair
consisting of 'ColorLimits'
and a twoelement 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  Mby3 array of RGB
Colormap for coloring propagation paths, specified as the
commaseparated pair consisting of 'Colormap'
and a
predefined color map name or an Mby3 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 commaseparated 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" 


"cartesian" 


^{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
MbyN cell array
Ray configuration, returned as a
MbyN 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 R2019bR2022b: 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 singleprecision floatingpoint 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 singleprecision floatingpoint 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
namevalue argument will be removed
The NumReflections
namevalue argument will be removed in a
future release. The NumReflections
namevalue argument now only
applies for the image ray tracing method. Instead, create a propagation model by
using the propagationModel
function with its
MaxNumReflections
namevalue 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.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)