Main Content

los

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

Description

example

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.

example

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

collapse all

Plot the LOS from the MathWorks Apple Hill campus to the MathWorks Lakeside campus.

Create a transmitter site with an antenna of height 30 m.

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

Create a receiver site with an antenna at ground level.

rx = rxsite('Name','MathWorks Lakeside', ...
   	    'Latitude',42.3021,'Longitude',-71.3764);

Plot the LOS between the two sites.

los(tx,rx);

Create a transmitter site with an antenna of height 30 m.

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

Create two receiver sites with antennas at ground level.

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 lines of sight to the receiver sites. The red portion of the LOS represents obstructed visibility.

los(tx,rxs);

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.

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

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

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 comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'ObstructedColor','blue'

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 NameShort NameRGB TripletAppearance
'red''r'[1 0 0]

Sample of the color red

'green''g'[0 1 0]

Sample of the color green

'blue''b'[0 0 1]

Sample of the color blue

'cyan' 'c'[0 1 1]

Sample of the color cyan

'magenta''m'[1 0 1]

Sample of the color magenta

'yellow''y'[1 1 0]

Sample of the color yellow

'black''k'[0 0 0]

Sample of the color black

'white''w'[1 1 1]

Sample of the color white

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 NameShort NameRGB TripletAppearance
'red''r'[1 0 0]

Sample of the color red

'green''g'[0 1 0]

Sample of the color green

'blue''b'[0 0 1]

Sample of the color blue

'cyan' 'c'[0 1 1]

Sample of the color cyan

'magenta''m'[1 0 1]

Sample of the color magenta

'yellow''y'[1 1 0]

Sample of the color yellow

'black''k'[0 0 0]

Sample of the color black

'white''w'[1 1 1]

Sample of the color white

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 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 SystemValid map valuesDefault map value
'geographic'
  • A siteviewer object[a].

  • 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

collapse all

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.

See Also

| |

Introduced in R2018a