# raytrace

Plot or compute propagation paths between sites

## Syntax

``raytrace(tx,rx)``
``raytrace(tx,rx,propmodel)``
``raytrace(___,Name,Value)``
``rays = raytrace(___)``

## Description

example

````raytrace(tx,rx)` plots the propagation paths from the transmitter site (`tx`) to the receiver site (`rx`). The propagation paths are found using ray tracing with surface geometry defined by the `Map` property. Each propagation path is color-coded according to the received power (dBm) or path loss (dB) along the path, assuming unpolarized rays. NoteThe ray tracing analysis includes surface reflections but does not include effects from refraction, diffraction, or scattering.Operational frequency for this function is from 100 MHz to 100 GHz. ```
````raytrace(tx,rx,propmodel)` plots 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)` plots propagation paths with additional options specified by one or more name-value pairs.```
````rays = raytrace(___)` returns the propagation paths in `rays`.```

## Examples

collapse all

`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 image method and performs line-of-sight and single-reflection analysis.

```pm = propagationModel("raytracing"); ssOneReflection = sigstrength(rx,tx,pm)```
```ssOneReflection = -54.0915 ```

Compute signal strength with analysis up to two reflections, where total received power is the cumulative power of all propagation paths

```pm.MaxNumReflections = 2; ssTwoReflections = sigstrength(rx,tx,pm)```
```ssTwoReflections = -52.3890 ```

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

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

Plot the propagation paths.

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

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. Specify the ray tracing method as shooting and bouncing rays (SBR).

```pm = propagationModel("raytracing", ... "Method","sbr", ... "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×3 104.2656 104.2744 112.0094 ```

Re-compute with material reflection loss by setting material type on 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×3 104.2656 106.2236 119.3577 ```

Appendix

Define a 3-D map for a conference room with one table and four chairs.

`mapFileName = "conferenceroom.stl";`

Visualize the 3-D map.

```figure; view(3); trisurf(stlread(mapFileName), 'FaceAlpha', 0.3, 'EdgeColor', 'none'); hold on; axis equal; grid off; xlabel('x'); ylabel('y'); zlabel('z');```

Define a transmitter site close to the wall and a receiver site under the table.

``` tx = txsite("cartesian", "AntennaPosition", [-1.45; -1.45; 1.5],"TransmitterFrequency", 2.8e9); rx = rxsite("cartesian","AntennaPosition", [.3; .2; .5]);```

Plot the transmitter site in red and receiver site in blue.

```scatter3(tx.AntennaPosition(1,:), tx.AntennaPosition(2,:), tx.AntennaPosition(3,:), 'sr', 'filled'); scatter3(rx.AntennaPosition(1,:), rx.AntennaPosition(2,:),rx.AntennaPosition(3,:), 'sb', 'filled');```

Create a ray tracing propagation model for Cartesian coordinates. Specify the ray tracing method as shooting and bouncing rays (SBR). Set the surface material to wood.

```pm = propagationModel("raytracing","CoordinateSystem","cartesian", ... "Method","sbr","MaxNumReflections",2,"SurfaceMaterial","wood"); ```

Perform ray tracing and save the computed rays using comm.Ray object

```rays = raytrace(tx, rx, pm, 'Map', mapFileName); rays = rays{1};```

Visualize rays in the 3D map.

```for i = 1:length(rays) if rays(i).LineOfSight propPath = [rays(i).TransmitterLocation, ... rays(i).ReceiverLocation]; else propPath = [rays(i).TransmitterLocation, ... rays(i).ReflectionLocations, ... rays(i).ReceiverLocation]; end line(propPath(1,:), propPath(2,:), propPath(3,:), 'Color', 'cyan'); end```

## Input Arguments

collapse all

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.

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.

Propagation model, specified as a character vector, a string, or a ray tracing propagation model created with the `propagationModel` function. The default propagation model is `'raytracing'`, a ray tracing propagation model that uses the image method.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

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

To perform ray tracing analysis using the shooting and bouncing rays (SBR) method instead, specify a propagation model created using the `propagationModel` function. This code shows how to create a propagation model that uses the SBR method.

`pm = propagationModel('raytracing','Method','sbr');`

For information about differences between the image and SBR methods, see Choose a Propagation Model.

Data Types: `char`

Number of reflections to search for in propagation paths using ray tracing, specified as the comma-separated pair consisting of `'NumReflections'` and a numeric row vector whose elements are `0`, `1`, or `2`.

The default value results in the search for line-of-sight propagation paths and single-reflection propagation paths.

This argument is only supported for ray tracing propagation models that use the image method. For ray tracing propagation models that use the SBR method, specify the `MaxNumReflections` property of the propagation model instead. For more information, see the `propagationModel` function.

Data Types: `double`

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

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`

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 the comma-separated pair consisting of `'Map` and one of the following depending on the coordinate system:

Coordinate SystemValid map valuesDefault map value
`'geographic'`
• A terrain name may be specified 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`

• current siteviewer or new siteviewer if none are open.

• `'gmted2010'` if called with an output.

`'cartesian'``'none'`, triangulation object or name of an STL file.`'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 objects representing all the rays found between the corresponding transmitter site and receiver site. array. Within each row vector, the `comm.Ray` objects are ordered by increasing number of reflections, and where number of reflections are equal they are ordered by increasing propagation distance.