los

Display or compute line-of-sight (LOS) visibility status

Syntax

los(site1,site2)

los(site1,site2,Name,Value)

vis = los(site1,site2,Name,Value)

Description

los(site1,site2) displays the line-of-sight (LOS) visibility from site 1 to site 2 in the current Site Viewer. The plot is color coded to identify the visibility of the points along the line.

los(site1,site2,Name,Value) sets properties using one or more name-value pairs. For example, los(site1,site2,'ObstructedColor','red') displays the LOS in red to show blocked visibility.

vis = los(site1,site2,Name,Value) returns the status of the LOS visibility.

Examples

LOS from a Transmitter Site to a Receiver Site

Create a transmitter site with an antenna of height 30 m and a receiver site at ground level.

tx = txsite("Name","MathWorks Apple Hill",...
      	"Latitude",42.3001,"Longitude",-71.3504,"AntennaHeight",30);
rx = rxsite("Name","MathWorks Lakeside", ...
   	    "Latitude",42.3021,"Longitude",-71.3764);

Plot the LOS between the two sites.

los(tx,rx)

LOS from a Transmitter Site to Two Receiver Sites

Create a transmitter site with an antenna of height 30 m and two receiver sites with antennas at ground level.

tx = txsite("Name","MathWorks Apple Hill",...
      	"Latitude",42.3001,"Longitude",-71.3504,"AntennaHeight",30);

names = ["Fenway Park","Bunker Hill Monument"];
lats = [42.3467,42.3763];
lons = [-71.0972,-71.0611];

Create the receiver site array.

rxs = rxsite("Name", names,...
      "Latitude",lats,...
      "Longitude",lons);

Plot the LOSs to the receiver sites. The red portion of the LOS represents obstructed visibility.

los(tx,rxs)

LOS Between Cartesian Sites

Import and view an STL file. The file models a small conference room with one table and four chairs.

viewer = siteviewer("SceneModel","conferenceroom.stl");

Create a transmitter site near the upper corner of the room and a receiver site above the table. Specify the position using Cartesian coordinates in meters.

tx = txsite("cartesian", ...
    "AntennaPosition",[-1.46; -1.42; 2.1]);
rx = rxsite("cartesian", ...
    "AntennaPosition",[0.3; 0.3; 0.85]);

Plot the LOS between the transmitter and the receiver.

los(rx,tx)

Pan by left-clicking, zoom by right-clicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and left-clicking and dragging.

Plot Propagation Rays Between Sites in Chicago

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

Input Arguments

site1 — Source antenna site

txsite object | rxsite object

Source antenna site, specified as a txsite object or a rxsite object. Site 1 must be a single site object.

site2 — Target antenna site

txsite object | rxsite object | vector of txsite or rxsite objects

Target antenna site, specified as a txsite object or a rxsite object. Site 2 can be a single site object or a vector of multiple site objects.

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: 'ObstructedColor','blue'

VisibleColor — Plot color for successful visibility

'green' (default) | RGB triplet | character vector | string scalar

Plot color for successful visibility, specified as one of the following:

• An RGB triplet whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A character vector such as 'red' or 'r'.

• A string scalar such as "red" or "r".

This table contains the color names and equivalent RGB triplets for some common colors.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

ObstructedColor — Plot color for blocked visibility

'red' (default) | RGB triplet | character vector | string scalar

Plot color for blocked visibility, specified as one of the following:

• An RGB triplet whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A character vector such as 'red' or 'r'.

• A string scalar such as "red" or "r".

This table contains the color names and equivalent RGB triplets for some common colors.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Resolution — Sampling distance between two sites

'auto' (default) | numeric scalar

Resolution of sample locations used to compute line-of-sight visibility, specified as 'auto' or a numeric scalar expressed in meters. Resolution defines the distance between samples on the great circle path using a spherical Earth model. If Resolution is 'auto', the function computes a value based on the distance between the sites.

Map — Map for visualization or surface data

siteviewer object | triangulation object | string scalar | character vector

Map for visualization or surface data, specified as a siteviewer object, a triangulation object, a string scalar, or a character vector. Valid and default values depend on the coordinate system.

Coordinate System	Valid map values	Default map value
"geographic"	A siteviewer objecta. A terrain name, if the function is called with an output argument. Valid terrain names are "none", "gmted2010", or the name of the custom terrain data added using addCustomTerrain.	The current siteviewer object or a new siteviewer object if none are open. "gmted2010", if the function is called with an output.
"cartesian"	"none". A siteviewer object. The name of an STL file. A triangulation object.	"none".
a Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

Data Types: char | string

Output Arguments

vis — Status of LOS visibility

true or 1 | false or 0 | n-by 1 logical array

Status of LOS visibility, returned as logical 1 (true) or 0 (false). If there are multiple target sites, the function returns a logical array of n-by-1.

Version History

Introduced in R2018a