Main Content

comm.Ray

Create RF propagation ray

Since R2020a

expand all in page

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.

example

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

expand all

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

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

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

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

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

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

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

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

Data Types: char | string

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

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

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

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

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

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

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

Signal frequency in Hz, specified as a positive scalar.

Data Types: double

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

Data Types: char | string

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

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

collapse all

Open Live Script

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

Site Viewer with buildings

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

Propagation paths from the transmitter site to the receiver site

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

Open Live Script

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

Site Viewer with buildings

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)

Obstructed line-of-sight path from the transmitter site to the receiver site. The path is green from the transmitter to the building, and red from the building to the receiver.

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)

Three propagation paths from the transmitter site to the receiver site

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

expand all

See Also

Functions

Objects

Topics