# raytrace

Plot 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 the terrain and buildings data defined in the Site Viewer map. Each propagation path is color-coded according to the received power (dBm) or path loss (dB) along the path. NoteThe ray tracing analysis includes surface reflections but does not include effects from refraction, diffraction, or scattering. ```
````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, please use the `'raytracing-image-method'` propagation model 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

Launch Site Viewer with buildings in Chicago.

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

Create transmitter site on a building.

```tx = txsite('Latitude',41.8800, ... 'Longitude',-87.6295, ... 'TransmitterFrequency',2.5e9);```

Create receiver site near another building.

```rx = rxsite('Latitude',41.881352, ... 'Longitude',-87.629771, ... 'AntennaHeight',30);```

Compute signal strength using ray tracing propagation model and default single-reflection analysis.

```pm = propagationModel("raytracing-image-method"); ssOneReflection = sigstrength(rx,tx,pm)```
```ssOneReflection = -55.2839 ```

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

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

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

Plot propagation paths.

`raytrace(tx, rx, pm) `

` `Launch Site Viewer with buildings in Hong Kong.` `

`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 ray tracing propagation model for perfect reflection.

```pm = propagationModel("raytracing-image-method", ... "BuildingsMaterial","perfect-reflector", ... "TerrainMaterial","perfect-reflector");```

` `Visualize 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.2745 112.0095 ```

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.2547 146.5527 ```

## 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 or string. You can also use the name-value pair `'PropagationModel'` to specify this parameter. You can also use the `propagationModel` function to define this input. The default propagation model is `'raytracing-image-method'`.

Data Types: `char` | `string`

### 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-image-method'` or a ray tracing propagation model object created using `propagationModel`.

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 a line-of-sight propagation path along with propagation paths that each contain a single reflection.

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 and surface data, specified as a `siteviewer` object. The default value is the current Site Viewer.

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