raytrace
Description
The raytrace
function plots or computes propagation
paths by using ray tracing with surface geometry defined by the 'Map'
property. The function
colorcodes each propagation path according to the received power (dBm) or path loss
(dB) from the transmitter site to the receiver site. The ray tracing analysis includes
surface reflections and edge diffractions, but does not include effects from corner
diffraction, refraction, or diffuse scattering. This function supports frequencies 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
)tx
to
the receiver site rx
in the current Site Viewer. By default,
the function uses the shooting and bouncing rays (SBR) method, finds paths with up
to two reflections and zero diffractions, and discards paths that are more than 40
dB weaker than the strongest path.
raytrace(
finds propagation paths using the ray tracing propagation model
tx
,rx
,propmodel
)propmodel
. Ray tracing propagation models enable you to
specify properties such as the maximum number of reflections and diffractions, path
loss thresholds, and building and terrain materials. Create a ray tracing
propagation model by using the propagationModel
function.
raytrace(___,
specifies options using one or more namevalue arguments, in addition to any
combination of inputs from the 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 a 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 and a receiver site near two different buildings.
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 the obstruction to the lineofsight path.
los(tx,rx)
Display propagation paths with reflections. By default, the raytrace
function uses the SBR method and calculates propagation paths 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);
Create a ray tracing propagation model, which MATLAB® represents using a RayTracing
object. By default, the propagation model uses the SBR method and finds propagation paths with up to two surface reflections.
pm = propagationModel("raytracing");
Calculate the signal strength using the receiver site, the transmitter site, and the propagation model.
ssTwoReflections = sigstrength(rx,tx,pm)
ssTwoReflections = 54.3015
Plot the propagation paths.
raytrace(tx,rx,pm)
Change the RayTracing
object to find paths with up to 5
reflections. Then, recalculate the signal strength.
pm.MaxNumReflections = 5; ssFiveReflections = sigstrength(rx,tx,pm)
ssFiveReflections = 53.3889
By default, RayTracing
objects assume that building and terrain materials are concrete. Change the building and terrain material types to model perfect electrical conductors.
pm.BuildingsMaterial = "perfectreflector";
ssPerfect = sigstrength(rx,tx,pm)
ssPerfect = 39.6711
Plot the propagation paths for the updated propagation model.
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
Launch Site Viewer with buildings in Hong Kong. For more information about the osm file, see [1].
viewer = siteviewer("Buildings","hongkong.osm");
Create transmitter and receiver sites that 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, which MATLAB represents using a RayTracing
object. Configure the model to use a low average number of degrees between launched rays, to find paths with up to 5 path reflections, and to use building and terrain material types that model perfect electrical conductors. By default, the model uses the SBR method.
pm = propagationModel("raytracing", ... "MaxNumReflections",5, ... "AngularSeparation","low", ... "BuildingsMaterial","perfectreflector", ... "TerrainMaterial","perfectreflector");
Visualize the propagation paths and calculate 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.5699 112.0092 109.3137 111.2840 111.9979 112.4416 108.1505 111.2825 111.3904 117.7506 116.5906 117.7638
Set the building and terrain material types to glass and concrete, respectively. Then, revisualize the propagation paths and recalculate the corresponding path losses. The model finds one fewer path because, by default, the model discards paths that are more than 40 decibels weaker than the strongest path. The first path loss value does not change 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×12
104.2656 106.1290 119.2409 121.2488 122.4103 121.5566 126.9462 124.1624 122.8190 127.5473 139.0664 140.5822
Incorporate atmospheric loss by adding rain and gas propagation models to the ray tracing model. Then, revisualize the propagation paths and recalculate the corresponding path losses.
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×12
105.3245 107.1887 121.8261 123.1442 124.9972 124.1457 129.6641 126.0587 125.4094 130.2653 143.0496 144.5656
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, which MATLAB represents using a RayTracing
object. Calculate rays that have up to 1
reflection and 1
diffraction. Set the surface material to wood. By default, the model uses the SBR method.
pm = propagationModel("raytracing", ... "CoordinateSystem","cartesian", .... "MaxNumReflections",1, ... "MaxNumDiffractions",1, ... "SurfaceMaterial","wood");
Calculate the propagation paths and return the result as a cell array of comm.Ray
objects. 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 you specify an
array, then the function plots propagation paths from each transmitter to
each receiver site.
rx
— Receiver site
rxsite
object  array of rxsite
objects
Receiver site, specified as an rxsite
object or an array of rxsite
objects. If you specify an
array, then the function plots propagation paths from each transmitter to
each receiver site.
propmodel
— Ray tracing propagation model
"raytracing"
(default)  RayTracing
object
Ray tracing propagation model, specified as
"raytracing"
or as a RayTracing
object. The default is
"raytracing"
, which uses the SBR method, finds paths
with up to two reflections and zero diffractions, and discards paths that
are more than 40 dB weaker than the strongest path.
Create a RayTracing
object by using the propagationModel
function. RayTracing
objects enable you to specify properties such as the ray tracing method, the
maximum number of reflections and diffractions, path loss thresholds, and
building and terrain materials.
For information about the differences between ray tracing methods, see Choose a Propagation Model.
Data Types: char
 string
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.
Example: raytrace(tx,rx,Type="pathloss")
colorcodes paths based
on path loss.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: raytrace(tx,rx,"Type","pathloss")
colorcodes paths
based on path loss.
Type
— Type of quantity to plot
"power"
(default)  "pathloss"
Type of quantity to plot, specified as one of these options:
"power"
— Colorcode paths based on the received power in dBm."pathloss"
— Colorcode paths based on path loss in dB.
The function uses a modified version of the Friis transmission equation to calculate received power (in logarithmic units):
$${P}_{rx}={P}_{tx}+{G}_{tx}+{G}_{rx}L{L}_{tx}{L}_{rx}$$
where:
P_{rx} is the received power at the receiver.
P_{tx} is the transmit power specified by the
TransmitterPower
property of the transmitter site.G_{tx} is the absolute antenna gain of the transmitter site in the direction of the angleofdeparture (AoD).
G_{rx} is the absolute antenna gain of the receiver site in the direction of the angleofarrival (AoA).
L is the path loss between the transmitter site and the receiver site.
L_{tx} is the system loss specified by the
SystemLoss
property of the transmitter site.L_{rx} is the system loss specified by the
SystemLoss
property of the receiver site.
Data Types: char
 string
PropagationModel
— Type of propagation model for ray tracing analysis
"raytracing"
(default)  RayTracing
object
Propagation model, specified as "raytracing"
or as
a RayTracing
object. The default is
"raytracing"
, which uses the SBR method, finds
paths with up to two reflections and zero diffractions, and discards
paths that are more than 40 dB weaker than the strongest path.
Create a RayTracing
object by using the propagationModel
function. RayTracing
objects enable you to specify properties such as the ray tracing method,
the maximum number of reflections and diffractions, path loss
thresholds, and building and terrain materials.
For information about the differences between ray tracing methods, see Choose a Propagation Model.
Data Types: char
 string
ColorLimits
— Color limits for colormap
twoelement numeric row vector
Color limits for the colormap, specified as a twoelement numeric row
vector of the form [min max]
.
The units and the default value depend on the value of
Type
:
"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. The function does not plot propagation paths with values that are below the minimum color limit.
Data Types: double
Colormap
— Colormap for coloring propagation paths
"jet"
(default)  colormap name  Mby3 array of RGB
Colormap for coloring the propagation paths, specified as a colormap
name or as an Mby3 array of RGB triplets that
define M individual colors. For more information
about colormap names, see colormap
.
Data Types: char
 string
 double
ShowLegend
— Show color legend in Site Viewer
true
or
1
(default)  false
or 0
Show color legend in Site Viewer, specified as a numeric or logical
1
(true
) or
0
(false
).
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
MbyN cell array of
comm.Ray
objects
Ray configuration, returned as a
MbyN cell array of comm.Ray
objects, 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 that represent the
propagation paths (rays) found between the corresponding transmitter site
and receiver site.
Within each row vector, the function sorts the comm.Ray
objects alphabetically by the first interaction type. When the first
interaction type for multiple rays is the same, the function sorts according
to the second interaction type and repeats this behavior for succeeding
repeated interaction types. When multiple comm.Ray
objects
have the same number and types of interactions in the same order, the
function sorts the objects by increasing propagation distance. If a
lineofsight path exists, the function includes it as the first
element.
Version History
Introduced in R2019bR2023a: Ray tracing models discard paths based on path loss
Ray tracing propagation models discard propagation paths based on path loss
thresholds. By default, when you specify the propmodel
input
argument as "raytracing"
or a RayTracing
object, the propagation model discards paths that are more than 40 dB weaker than
the strongest path.
As a result, the raytrace
function can return different
values in R2023a compared to previous releases. To avoid discarding paths based on
relative path loss thresholds, create a RayTracing
object (by using
the propagationModel
function) and set its
MaxRelativePathLoss
property to Inf
.
Then, use the object as input to the raytrace
function.
R2023a: Ray tracing with SBR method calculates paths using increased precision
When you find propagation paths by using the raytrace
function with a ray tracing model that uses the shooting and bouncing rays (SBR)
method, MATLAB^{®} calculates the results using doubleprecision floatingpoint
computations. In previous releases, the function used singleprecision
floatingpoint computations.
As a result, the raytrace
function can return different
comm.Ray
objects in R2023a compared to previous
releases.
R2023a: NumReflections
namevalue argument has been removed
The NumReflections
namevalue argument has been removed.
Instead, create a propagation model by using the propagationModel
function and specify the
MaxNumReflections
namevalue argument. Then, use the
raytrace
function with the propagation model as an input.
This code shows the recommended workflow.
pm = propagationModel("raytracing",MaxNumReflections=3);
rays = raytrace(tx,rx,pm);
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 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 issues a warning that it
will be removed in a future release.
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)