# 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

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

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 = -52.4056 ```

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 = -51.8927 ```

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

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

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

`raytrace(tx,rx,pm)`

Appendix

Path loss due to material reflection and atmosphere in Hong Kong. Configure ray tracing 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 corresponding path losses.

```raytrace(tx,rx,pm,"Type","pathloss") raysPerfect = raytrace(tx,rx,pm,"Type","pathloss"); plPerfect = [raysPerfect{1}.PathLoss]```
```plPerfect = 1×15 104.2656 104.2744 112.0095 109.3152 112.0156 112.0375 112.4436 109.3198 112.0406 112.0406 112.4444 112.4444 117.7513 117.7524 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×15 104.2656 106.2236 119.3577 121.5812 122.2841 121.4389 127.0060 122.4593 122.7023 122.6987 127.3370 127.4156 139.1007 139.6484 153.4365 ```

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×15 105.3245 107.2834 121.9430 123.4766 124.8711 124.0280 129.7238 124.3557 125.2930 125.2895 130.0564 130.1335 143.0838 143.6317 157.4225 ```

Appendix

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

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.

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.

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

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`

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

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

Data Types: `logical`

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'`
• 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 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 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

Warns starting in R2022a

Behavior changed in R2021b