comm.Ray

Create RF propagation ray

Since R2020a

Description

A comm.Ray object contains the properties of an RF propagation ray. The object contains the geometric and electromagnetic information of a radio wave (approximated as a ray) that propagates from one point to another point.

Creation

Typically you create comm.Ray objects by using the raytrace function.

Syntax

ray = comm.Ray

ray = comm.Ray(Name=Value)

Description

ray = comm.Ray creates a default RF propagation ray object.

ray = comm.Ray(Name=Value) sets properties using one or more name-value arguments. For example, comm.Ray(CoordinateSystem="geographic",TransmitterLocation=[40.730610;-73.935242;0]) creates a ray referenced to a geographic coordinate system with a transmitter located in New York City.

Properties

PathSpecification — Propagation path specification method

'Locations' (default) | 'Delay and angles'

Propagation path specification method, specified as one of these values.

• 'Locations' — The ray object path between waypoints are conveyed as (x, y, z) coordinate points by the TransmitterLocation, ReceiverLocation, and, if applicable, Interactions properties.

• 'Delay and angles' — The ray object path between waypoints are conveyed by the PropagationDelay, AngleOfDeparture, and AngleOfArrival properties.

Data Types: char | string

CoordinateSystem — Coordinate system

'Cartesian' (default) | 'Geographic'

Coordinate system, specified as 'Cartesian' or 'Geographic'. When you set the CoordinateSystem property to 'Geographic', the coordinate system is defined relative to the WGS-84 Earth ellipsoid model and the object defines angles relative to the local East-North-Up (ENU) coordinate system at the transmitter and receiver.

Dependencies

To enable this property, the PathSpecification property must be 'Locations'.

Data Types: char | string

SystemScale — Cartesian coordinate system scale, in meters

1 (default) | positive scalar

Cartesian coordinate system scale, in meters, specified as a positive scalar.

Dependencies

To enable this property, the PathSpecification property must be 'Locations' and the CoordinateSystem property must be 'Cartesian'.

Data Types: double

TransmitterLocation — Transmitter location

[0;0;0] (default) | three-element numeric column vector

Transmitter location, specified as a three-element numeric column vector of coordinates in one of these forms.

• [x; y; z] — This form applies when you set the CoordinateSystem property to 'Cartesian'. The object does not perform range validation for x, y, and z.

• [latitude; longitude; height] — This form applies when you set the CoordinateSystem property to 'Geographic'. latitude must be in the range [–90, 90]. The object does not perform range validation for longitude and height. height is referenced to the ellipsoid defined by the World Geodetic System of 1984 (WGS84).

Dependencies

To enable this property, the PathSpecification property must be 'Locations'.

Data Types: double

ReceiverLocation — Receiver location

[10;10;10] (default) | three-element numeric column vector

Receiver location, specified as a three-element numeric column vector of coordinates in one of these forms.

• [x; y; z] — This form applies when you set the CoordinateSystem property to 'Cartesian'. The object does not perform range validation for x, y, and z.

• [latitude; longitude; height] — This form applies when you set the CoordinateSystem property to 'Geographic'. latitude must be in the range [–90, 90]. The object does not perform range validation for longitude and height. height is referenced to the ellipsoid defined by the World Geodetic System of 1984 (WGS84).

Dependencies

To enable this property, the PathSpecification property must be 'Locations'.

Data Types: double

LineOfSight — Line-of-sight indicator

true or 1 (default) | false or 0

Line-of-sight indicator, specified as logical 1 (true) or 0 (false).

• A value of 1 (true) means that the ray has an unobstructed path from the transmitter to the receiver.

• A value of 0 (false) means that path from the transmitter to the receiver is obstructed.

Dependencies

To enable this property, the PathSpecification property must be 'Locations'.

Data Types: logical

Interactions — Ray-interface interactions along propagation path

1-by-N_I structure

Ray-interface interactions along the propagation path, specified as a 1-by-N_I structure containing these fields. N_I is the number of interactions.

Type — Type of ray-interface interaction

'Reflection' (default) | 'Diffraction'

Type of ray-interface interaction, specified as 'Reflection' or 'Diffraction'.

Data Types: char | string

Location — Location of ray-interface interaction

[10;10;0] (default) | 3-by-1 numeric vector

Location of the ray-interface interaction, specified as a 3-by-1 numeric vector containing the coordinates of one interaction point on the ray.

• When the CoordinateSystem property is set to 'Cartesian', the form is [x; y; z]. The object does not perform range validation for x, y, and z.

• When the CoordinateSystem property is set to 'Geographic', the form is [latitude; longitude; height]. The latitude must be in the range [–90, 90]. The object does not perform range validation for longitude and height. height is referenced to the ellipsoid defined by the World Geodetic System of 1984 (WGS84).

Data Types: double

MaterialName — Name of material associated with ray-interface interaction

"" (default) | string scalar

Name of the material associated with the ray-interface interaction, specified as a string scalar.

Data Types: char | string

Dependencies

To enable this property, the PathSpecification property must be 'Locations' and the LineOfSight property must be 0 (false).

Data Types: struct

PropagationDelay — Propagation delay in seconds

5.7775e-08 (default) | nonnegative scalar

Propagation delay in seconds, specified as a nonnegative scalar. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathSpecification property to 'Locations', this property is read-only and the value is derived from TransmitterLocation, ReceiverLocation and, if applicable, the Interactions.

• When you set the PathSpecification property to 'Delay and angles', this property is configurable.

Data Types: double

PropagationDistance — Propagation distance in meters

17.3205 (default) | nonnegative scalar

This property is read-only.

Propagation distance in meters, specified as a nonnegative scalar. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathSpecification property to 'Locations', the value is derived from TransmitterLocation, ReceiverLocation and, if applicable, the Interactions.

• When you set the PathSpecification property to 'Delay and angles', the value is derived from PropagationDelay.

Data Types: double

AngleOfDeparture — Angle of departure, in degrees

[45; 35.2644] (default) | numeric vector of the form [az; el]

Angle of departure, in degrees, of the ray departing the transmitter, specified as a numeric vector of the form [az; el]. The azimuth angle, az, is measured from the positive x-axis counterclockwise around the z-axis and must be in the range (–180, 180]. The elevation angle, el, is measured from the xy-plane and must be in the range [–90, 90]. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathSpecification property to 'Delay and angles', this property is configurable.

• When you set the PathSpecification property to 'Locations', this property is read-only and the value is derived from TransmitterLocation, ReceiverLocation and, if applicable, the Interactions.

• When CoordinateSystem is set to 'Geographic', the angles are defined with reference to the local East-North-Up (ENU) coordinate system at transmitter.

Data Types: double

AngleOfArrival — Angle of arrival, in degrees

[-135; -35.2644] (default) | numeric vector of the form [az; el]

Angle of arrival, in degrees, of the ray arriving at the receiver, specified as a numeric vector of the form [az; el]. The azimuth angle, az, is measured from the positive x-axis counterclockwise around the z-axis and must be in the range (–180, 180]. The elevation angle, el, is measured from the xy-plane and must be in the range [–90, 90]. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathSpecification property to 'Delay and angles', this property is configurable.

• When you set the PathSpecification property to 'Locations', this property is read-only and the value is derived from TransmitterLocation, ReceiverLocation and, if applicable, the Interactions.

• When CoordinateSystem is set to 'Geographic', the angles are defined with reference to the local East-North-Up (ENU) coordinate system at receiver.

Data Types: double

NumInteractions — Number of ray-interface interactions

0 (default) | nonnegative integer

This property is read-only.

Number of ray-interface interactions for the ray object from the transmitter to the receiver, specified as a nonnegative integer. The value is derived from LineOfSight and, if applicable, Interactions.

Dependencies

To enable this property, the PathSpecification property must be 'Locations'.

Data Types: double

Frequency — Signal frequency in Hz

1.9e+09 (default) | positive scalar

Signal frequency in Hz, specified as a positive scalar.

Data Types: double

PathLossSource — Path loss source

'Free space model' (default) | 'Custom'

Path loss source, specified as 'Free space model' or 'Custom'.

Data Types: char | string

PathLoss — Path loss in dB

62.7941 (default) | nonnegative scalar

Path loss in dB, specified as a nonnegative scalar. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathLossSource property to 'Free space model', the PathLoss property is read-only and derived from the PropagationDistance and Frequency properties by using the free space propagation model.

• When you set the PathLossSource property to 'Custom', you can set the PathLoss property, independent of the geometric properties.

Data Types: double

PhaseShift — Phase shift in radians

4.8537 (default) | numeric scalar

Phase shift in radians, specified as a numeric scalar. The default value is computed using the default values of the TransmitterLocation and ReceiverLocation properties for a line-of-sight ray.

• When you set the PathLossSource property to 'Free space model', the PhaseShift property is read-only and derived from the PropagationDistance and Frequency properties by using the free space propagation model.

• When you set the PathLossSource property to 'Custom', you can set the PhaseShift property, independent of the geometric properties.

Data Types: double

Object Functions

plot (rays)

Display RF propagation rays in Site Viewer

Examples

Perform Ray Tracing Between Two Sites in Hong Kong

Perform ray tracing in Hong Kong and return the rays in comm.Ray objects. The comm.Ray objects contain geometric and electromagnetic information for propagation paths between the transmitter and receiver sites.

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

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

Create transmitter and receiver sites.

tx = txsite(Latitude=22.2789,Longitude=114.1625, ...
    AntennaHeight=10,TransmitterPower=5, ...
    TransmitterFrequency=28e9);
rx = rxsite(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 find paths with up to 3 surface reflections and up to 1 edge diffraction. By default, the model uses the shooting and bouncing rays (SBR) method.

pm = propagationModel("raytracing",MaxNumReflections=3,MaxNumDiffractions=1);

Perform the ray tracing analysis. The raytrace function returns a cell array containing the comm.Ray objects. By default, ray tracing models discard rays that are more than 40 decibels weaker than the strongest path.

rays = raytrace(tx,rx,pm)

rays = 1×1 cell array
    {1×15 comm.Ray}

Display the properties of the first comm.Ray object. The value of the LineOfSight property is 1, and value of the NumInteractions property is 0. This combination indicates that the ray defines a line-of-sight path.

rays{1}(1)

ans = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 1
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 104.2656
             PhaseShift: 4.6406

   Read-only properties:
       PropagationDelay: 4.6442e-07
    PropagationDistance: 139.2294
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
        NumInteractions: 0

Display the properties of the third comm.Ray object. The value of the LineOfSight property is 0, and the value of the NumInteractions property is 2. This combination indicates that the ray defines a path with two interface interactions.

rays{1}(3)

ans = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 0
           Interactions: [1×2 struct]
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 142.4192
             PhaseShift: 0.7186

   Read-only properties:
       PropagationDelay: 8.3065e-07
    PropagationDistance: 249.0217
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
        NumInteractions: 2

Display the interaction types, locations, and materials by querying the Interactions property.

rays{1}(3).Interactions(1)

ans = struct with fields:
            Type: 'Diffraction'
        Location: [3×1 double]
    MaterialName: "concrete"

rays{1}(3).Interactions(2)

ans = struct with fields:
            Type: 'Reflection'
        Location: [3×1 double]
    MaterialName: "concrete"

Visualize the sites and the ray tracing paths.

show(tx)
show(rx)
plot(rays{1})

Appendix

[1] The OpenStreetMap 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/.

Plot Propagation Rays Between Sites in Chicago

Perform ray tracing in Chicago and return the rays in comm.Ray objects. Then, display the rays without performing the ray tracing analysis again.

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

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

Create a transmitter site on one building and a receiver site on another building. Show the line-of-sight path between the sites using the los function.

tx = txsite(Latitude=41.8800, ...
    Longitude=-87.6295, ...
    TransmitterFrequency=2.5e9);
rx = rxsite(Latitude=41.881352, ...
    Longitude=-87.629771, ...
    AntennaHeight=30);
los(tx,rx)

Create a ray tracing propagation model, which MATLAB® represents using a RayTracing object. By default, the model uses the SBR method and calculates propagation paths with up to two reflections.

pm = propagationModel("raytracing");

Perform the ray tracing analysis. The raytrace function returns a cell array containing the comm.Ray objects.

rays = raytrace(tx,rx,pm)

rays = 1×1 cell array
    {1×3 comm.Ray}

View the properties of the first ray object.

rays{1}(1)

ans = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 0
           Interactions: [1×1 struct]
              Frequency: 2.5000e+09
         PathLossSource: 'Custom'
               PathLoss: 92.7686
             PhaseShift: 1.2945

   Read-only properties:
       PropagationDelay: 5.7088e-07
    PropagationDistance: 171.1462
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
        NumInteractions: 1

Close Site Viewer.

close(viewer)

Create another Site Viewer with the same buildings, transmitter site, and receiver site. Then, display the propagation paths. Alternatively, you can plot individual paths by specifying a single ray object, for example rays{1}(2).

siteviewer(Buildings="chicago.osm");
show(tx)
show(rx)
plot(rays{1},Type="power", ...
    TransmitterSite=tx,ReceiverSite=rx)

Appendix

[1] The OpenStreetMap 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/.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2020a

R2021b: ReflectionLocations and NumReflections properties have been removed

The ReflectionLocations and NumReflections properties have been removed. To accommodate reflections, use the Interactions property to replace the ReflectionLocations property and use the NumInteractions property to replace the NumReflections property.