comm.Ray
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.
Description
creates a default RF
propagation ray object.ray
= comm.Ray
sets properties using one or more name-value arguments. For example,
ray
= comm.Ray(Name=Value
)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 theTransmitterLocation
,ReceiverLocation
, and, if applicable,Interactions
properties.'Delay and angles'
— The ray object path between waypoints are conveyed by thePropagationDelay
,AngleOfDeparture
, andAngleOfArrival
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-NI structure
Ray-interface interactions along the propagation path, specified as a 1-by-NI structure containing these fields. NI 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 fromTransmitterLocation
,ReceiverLocation
and, if applicable, theInteractions
.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 fromTransmitterLocation
,ReceiverLocation
and, if applicable, theInteractions
.When you set the
PathSpecification
property to'Delay and angles'
, the value is derived fromPropagationDelay
.
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 fromTransmitterLocation
,ReceiverLocation
and, if applicable, theInteractions
.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 fromTransmitterLocation
,ReceiverLocation
and, if applicable, theInteractions
.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'
, thePathLoss
property is read-only and derived from thePropagationDistance
andFrequency
properties by using the free space propagation model.When you set the
PathLossSource
property to'Custom'
, you can set thePathLoss
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'
, thePhaseShift
property is read-only and derived from thePropagationDistance
andFrequency
properties by using the free space propagation model.When you set the
PathLossSource
property to'Custom'
, you can set thePhaseShift
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 R2020aR2021b: 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.
See Also
Functions
Objects
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)