Main Content

comm.Ray

Create RF propagation ray

expand all in page

Description

The comm.Ray object is a container object for the properties of a propagation ray. The object contains the geometric and electromagnetic information of a radio wave propagating from one point to another point in the space.

Creation

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

Syntax

ray = comm.Ray
ray = comm.Ray(Name,Value)

Description

example

ray = comm.Ray creates a ray object that initializes properties for a propagation ray.

ray = comm.Ray(Name,Value) sets properties using one or more name-value pair arguments. Enclose each property name in quotes. For example, comm.Ray('CoordinateSystem','Geographic','TransmitterLocation',[40.730610,-73.935242,0]) specifies the geographic coordinate system and 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, ReflectorLocations 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, set the PathSpecification property to 'Locations'.

Data Types: char | string

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

Dependencies

To enable this property, set the PathSpecification property to 'Locations' and the CoordinateSystem property to '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, set the PathSpecification property to '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, set the PathSpecification property to 'Locations'.

Data Types: double

Line of sight, specified as a logical value of 1 (true) or 0 (false) to indicate whether the ray is a line-of-sight ray.

Dependencies

To enable this property, set the PathSpecification property to 'Locations'.

Data Types: logical

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

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

Data Types: char | string

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

Dependencies

To enable this property, set the PathSpecification property to 'Locations' and the LineOfSight property to 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 at the transmitter, specified as a numeric vector of the form [az; el]. The azimuth angle, az, is measured from the positive x-axis counterclockwise and must be in the range (–180, 180]. The elevation angle, el, is measured from the x-y 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 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 and must be in the range (–180, 180]. The elevation angle, el, is measured from the x-y 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-surface 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, the Interactions.

Dependencies

To enable this property, set the PathSpecification property to '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 between two sites in Hong Kong, generating a cell array containing comm.Ray objects. The comm.Ray objects contain the geometric and electromagnetic information for the radio wave propagation paths from the transmitter site to the receiver site.

Create a Site Viewer map, loading building data for Hong Kong. For more information about the osm file, see [1].

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

Specify 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);
show(tx)
show(rx)

Specify a ray tracing propagation model that uses the SBR method with up to three reflections.

pm = propagationModel("raytracing", ...
    "Method","sbr", ...
    "MaxNumReflections",3);

Perform ray tracing between the sites, generating comm.Ray objects in a cell array. For the specified transmitter and receiver sites, performing ray tracing results in a 1-by-1 cell array containing three ray objects in a row vector.

rays = raytrace(tx,rx,pm)
rays = 1×1 cell array
    {1×11 comm.Ray}

Display the properties of the first comm.Ray object. The LineOfSight property value is 1, and the NumInteractions property value 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.6360

   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 second and third comm.Ray objects. The LineOfSight property values are 0, and the NumInteractions property values are greater than 0. This combination indicates that the rays define reflected paths.

rays{1}(2)
ans = 
  Ray with properties:

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

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


rays{1}(3)
ans = 
  Ray with properties:

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

   Read-only properties:
       PropagationDelay: 1.1327e-06
    PropagationDistance: 339.5692
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
        NumInteractions: 1

Visualize ray tracing results.

plot(rays{1})

Appendix

[1] The osm 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

Return ray tracing results in comm.Ray objects and plot the ray propagation paths after relaunching the Site Viewer map.

Create a Site Viewer map, loading building data for Chicago. For more information about the osm file, see [1].

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

Create a transmitter site on one building and a receiver site on another building. Use the los function to show the line of sight path between the transmitter and receiver sites. 

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

Perform ray tracing for up to two reflections. For the configuration defined, ray tracing returns a cell array containing the ray objects. Close the Site Viewer map.

pm = propagationModel( ...
    "raytracing", ...
    "Method","sbr", ...
    "MaxNumReflections",2);
rays = raytrace(tx,rx,pm)
rays = 1×1 cell array
    {1×3 comm.Ray}


rays{1}(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.7739
             PhaseShift: 1.2933

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


rays{1}(1,2)
ans = 
  Ray with properties:

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

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


rays{1}(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.5000e+09
         PathLossSource: 'Custom'
               PathLoss: 106.3302
             PhaseShift: 4.6994

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


close(viewer)

You can plot the rays without performing ray tracing again. Create another Site Viewer map with the same buildings. Show the transmitter and receiver sites. Using the previously returned cell array of ray objects, plot the reflected rays between the transmitter site and the receiver site. The plot function can plot the path for ray objects collectively or individually. For example, to plot rays for the only second ray object, specify rays{1}(1,2). This figure plot all paths for all the ray objects. 

siteviewer("Buildings","chicago.osm")
ans = 
  siteviewer with properties:

                Name: 'Site Viewer'
            Position: [560 240 800 600]
    CoordinateSystem: "geographic"
             Basemap: 'satellite'
             Terrain: 'gmted2010'
           Buildings: 'chicago.osm'


los(tx,rx)
plot(rays{:},"Type","power", ...
    "TransmitterSite",tx,"ReceiverSite",rx)

Appendix

[1] The osm 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