Main Content

raytrace

Display or compute RF propagation rays

Since R2019b

Description

The raytrace function plots or computes propagation paths by using ray tracing with surface geometry defined by the 'Map' property. The function color-codes 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.

example

raytrace(tx,rx) displays the propagation paths from the transmitter site 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.

example

raytrace(tx,rx,propmodel) finds propagation paths using the ray tracing propagation model 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(___,Name,Value) specifies options using one or more name-value arguments, in addition to any combination of inputs from the previous syntaxes.

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

Examples

collapse all

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 line-of-sight path.

los(tx,rx)

Obstructed line-of-sight path from the transmitter site to the receiver site. The path is green from the transmitter to the building, and red from the building to the receiver.

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)

Three propagation paths from the transmitter site to the receiver site

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

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

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

Site Viewer with buildings

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) 

Three propagation paths from the transmitter site to the receiver site

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 = "perfect-reflector";
ssPerfect = sigstrength(rx,tx,pm)
ssPerfect = -39.6711

Plot the propagation paths for the updated propagation model.

raytrace(tx,rx,pm)

Additional propagation paths from the transmitter site to the receiver site

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

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

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

Site Viewer with buildings

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","perfect-reflector", ...
    "TerrainMaterial","perfect-reflector");

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

Propagation paths from the transmitter site to the receiver site

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 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×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

Updated propagation paths from the transmitter site to the receiver site

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

Updated propagation paths from transmitter site to receiver site

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

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);

Site Viewer with conference room model

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.

The same Site Viewer with a transmitter site and receiver site

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.

Propagation paths between the transmitter site and receiver site. A legend shows information about a propagation path.

Input Arguments

collapse all

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.

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.

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

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.

Example: raytrace(tx,rx,Type="pathloss") color-codes 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") color-codes paths based on path loss.

Type of quantity to plot, specified as one of these options:

  • "power" — Color-code paths based on the received power in dBm.

  • "pathloss" — Color-code 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):

Prx=Ptx+Gtx+GrxLLtxLrx

where:

  • Prx is the received power at the receiver.

  • Ptx is the transmit power specified by the TransmitterPower property of the transmitter site.

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

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

  • L is the path loss between the transmitter site and the receiver site.

  • Ltx is the system loss specified by the SystemLoss property of the transmitter site.

  • Lrx is the system loss specified by the SystemLoss property of the receiver site.

Data Types: char | string

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

Color limits for the colormap, specified as a two-element 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 for coloring the propagation paths, specified as a colormap name or as an M-by-3 array of RGB triplets that define M individual colors. For more information about colormap names, see colormap.

Data Types: char | string | double

Show color legend in Site Viewer, specified as a numeric or logical 1 (true) or 0 (false).

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 SystemValid map valuesDefault map value
"geographic"
  • A siteviewer objecta.

  • 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

Ray configuration, returned as a M-by-N 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 line-of-sight path exists, the function includes it as the first element.

Version History

Introduced in R2019b

expand all