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

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

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 a glTF™ file 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®.

In most cases, if you specify this argument as a value other than a siteviewer or "none", then you must also specify an output argument.

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 R2019b