Main Content

plot (rays), plot

Display RF propagation rays in Site Viewer

Since R2020a

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

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

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