comm.Ray

Propagation ray container object

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 container 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], and height must be nonnegative. The object does not perform range validation for longitude.

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], and height must be nonnegative. The object does not perform range validation for longitude.

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

Reflector locations, specified as a 3-by-N numeric matrix containing the coordinates of the reflection points for the ray. N is the number of reflection points for the ray and is set by the NumReflections property. Each column represents the coordinate location of one reflection point along the propagation path from transmitter to receiver. The order of the columns is the same as the order of the points along the path. Columns (reflection point coordinates) are of one of these forms.

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

  • [latitude; longitude; height] — when the CoordinateSystem property is set to 'Geographic'. latitude must be in the range [–90, 90], and height must be nonnegative. The object does not perform range validation for longitude.

Dependencies

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

.

Data Types: double

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

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

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

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

  • 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 reflection points 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 ReflectionLocations.

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)Plot rays in Site Viewer map

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

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,'Type','pathloss','ColorLimits',[100 250])
rays = 1×1 cell array
    {1×3 comm.Ray}

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

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

Display the properties of the second and third comm.Ray objects. The LineOfSight property values are 0, and the NumReflections 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
    ReflectionLocations: [3×1 double]
              Frequency: 2.8000e+10
         PathLossSource: 'Custom'
               PathLoss: 106.2545
             PhaseShift: 0.3951

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


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

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

   Read-only properties:
       PropagationDelay: 1.1327e-06
    PropagationDistance: 339.5692
       AngleOfDeparture: [2×1 double]
         AngleOfArrival: [2×1 double]
         NumReflections: 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 path 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 and show a transmitter site on one building and a receiver site on another building.

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

Perform ray tracing, returning the ray object results. For the configuration defined, ray tracing returns a cell array containing one ray object. Display the ray object properties. Then, close the Site Viewer map.

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


rays{1}
ans = 
  Ray with properties:

      PathSpecification: 'Locations'
       CoordinateSystem: 'Geographic'
    TransmitterLocation: [3×1 double]
       ReceiverLocation: [3×1 double]
            LineOfSight: 0
    ReflectionLocations: [3×1 double]
              Frequency: 2.5000e+09
         PathLossSource: 'Custom'
               PathLoss: 94.0915
             PhaseShift: 1.2939

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


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 one ray object at a time.

siteviewer('Buildings','chicago.osm');
show(tx);
show(rx);
plot(rays{1},'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™.

See Also

Functions

Objects

Introduced in R2020a

Antenna Toolbox Documentation

Support