raytrace

Display or compute RF propagation rays

Since R2019b

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

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

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

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

Plot the propagation paths for the updated propagation model.

`raytrace(tx,rx,pm)`

Appendix

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

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

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

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

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

`${P}_{rx}={P}_{tx}+{G}_{tx}+{G}_{rx}-L-{L}_{tx}-{L}_{rx}$`

where:

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