Main Content

plot (rays), plot

Display RF propagation rays in Site Viewer

collapse all in page

Syntax

plot(rays)
plot(rays,Name,Value)

Description

example

plot(rays) plots the propagation paths for ray objects in the Site Viewer map.

plot(rays,Name,Value) plots the propagation paths for ray objects in the Site Viewer map with additional options specified by one or more name-value pair arguments.

Examples

collapse all

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: 94.1067
             PhaseShift: 1.1472

   Read-only properties:
       PropagationDelay: 5.7089e-07
    PropagationDistance: 171.1479
       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: 101.8769
             PhaseShift: 2.8594

   Read-only properties:
       PropagationDelay: 5.9279e-07
    PropagationDistance: 177.7143
       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: 99.1597
             PhaseShift: 4.6635

   Read-only properties:
       PropagationDelay: 6.3790e-07
    PropagationDistance: 191.2388
       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');
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/.

Input Arguments

collapse all

Ray configuration, specified as one comm.Ray object or a vector of comm.Ray objects. Each object must have the PathSpecification property set to "Locations".

Data Types: comm.Ray

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: plot(rays,"Type","pathloss","ColorLimits",[-100 0]) adds the propagation path specified in rays to the current Site Viewer and adjusts the default color limits.

Quantity type to plot, specified as "pathloss" or "power". Based on the value specified for Type, the color applied along the path maps to the path loss in dB or the power in dBm of the signal along the path.

Data Types: char | string

Transmitter site, specified as a txsite object.

Dependencies

Applies only when Type is set to "power".

Data Types: char

Receiver site, specified as an rxsite object.

Dependencies

Applies only when Type is set to "power".

Data Types: char

Color limits for colormap, specified as a 1-by-2 numeric vector, [min, max], where min represents the lower saturation limit and max represents the upper saturation limit. The default is [-120 -5] when Type is set to 'power' and [45 160] when Type is set to 'pathloss'.

Data Types: double

Colormap applied to propagation path, specified as an M-by-3 numeric array of RGB (red,green,blue) triplets that define M individual colors.

Data Types: double | char | string

Show color legend on map, specified as true or false.

Data Types: logical

Map for visualization and surface data, specified as a siteviewer object.1 The default is the current siteviewer object, or if no Site Viewer is open a new siteviewer object opens.

Data Types: siteviewer object

Version History

Introduced in R2020a

See Also

Functions

Objects

1 Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.