los2

Line-of-sight visibility between two points on or above terrain

Syntax

vis = los2(Z,R,lat1,lon1,lat2,lon2)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref,rad)

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref,rad,effectiveRad)

[vis,visprofile,dist,h,lattrk,lontrk] = los2(___)

los2(___)

[___] = los2

Description

Specify Coordinates and Heights

vis = los2(Z,R,lat1,lon1,lat2,lon2) determines whether the point specified by lat1 and lon1 has line-of-sight visibility with the point specified by lat2 and lon2. Specify spatially referenced terrain data, in meters, using Z and R. This function assumes that the Earth is a sphere.

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1) specifies the height, in meters, of the first point.

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2) specifies the height, in meters, of the second point.

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref) references the height of the first point to either the terrain (ground level) or the sphere (mean sea level).

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref) references the height of the second point to either the terrain (ground level) or the sphere (mean sea level).

Specify Reference Sphere

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref,rad) specifies the radius in meters of the reference sphere. This syntax is useful for finding line-of-sight visibility for planetary bodies other than Earth.

vis = los2(Z,R,lat1,lon1,lat2,lon2,h1,h2,h1ref,h2ref,rad,effectiveRad) specifies a larger radius for the propagation of line-of-sight paths. You can use this syntax to account for the curvature of signal paths due to refraction in the atmosphere.

Query Intermediate Points

[vis,visprofile,dist,h,lattrk,lontrk] = los2(___) determines line-of-sight visibility for intermediate points between the first and second points, using any combination of input arguments from the previous syntaxes. For each intermediate point, the function returns the visibility in visprofile, the distance from the first point in dist, the height in h, the latitude in lattrk, and the longitude in lontrk. The number of intermediate points depends on the resolution of the terrain data.

Display and Interactively Select Coordinates

los2(___) displays the visibility profile between the two points in a new figure on Cartesian axes. The figure illustrates the terrain, the observer, the line of sight, the visible points, and the obstructed points.

[___] = los2 enables you to interactively select two points on the current axesm-based map and then determines whether the points have line-of-sight visibility, returning any combination of output arguments from previous syntaxes. If the current object on the map is a surface, then the function uses the z-coordinate data (the ZData property) as the terrain elevation data. Otherwise, the function uses z-coordinate data from the first surface it finds on the map. If the surface does not have z-coordinate data, then the function uses the color data (the CData property), instead.

Examples

Determine Line-of-Sight Visibility

Determine whether two points have line-of-sight visibility. Then, display the visibility profile.

Read terrain data for an area around South Boulder Peak into the workspace as an array and a reference object. Prepare the data for analysis by specifying the output type as "double".

[Z,R] = readgeoraster("n39_w106_3arc_v2.dt1","OutputType","double");

Specify the coordinates of South Boulder Peak and a nearby point.

lat1 = 39.95384;
lon1 = -105.29916;
lat2 = 39.96955;
lon2 = -105.29867;

Determine whether the nearby point is visible from a location 100 meters above the peak. The result indicates that the points do not have line-of-sight visibility.

h1 = 100;
vis = los2(Z,R,lat1,lon1,lat2,lon2,h1)

vis = logical
   0

Display the visibility profile by omitting the output argument.

los2(Z,R,lat1,lon1,lat2,lon2,h1)

View Visibility Profile in 3-D

To view a visibility profile in 3-D, calculate the profile using the los2 function and display the profile using the geoglobe and geoplot3 functions.

Read terrain data for an area around South Boulder Peak into the workspace as an array and a reference object. Prepare the data for analysis by specifying the output type as "double".

[Z,R] = readgeoraster("n39_w106_3arc_v2.dt1","OutputType","double");

Specify the coordinates of South Boulder Peak and a nearby point.

lat1 = 39.95384;
lon1 = -105.29916;
lat2 = 39.96955;
lon2 = -105.29867;

Determine whether the nearby point is visible from a location 100 meters above the peak. The result indicates that the points do not have line-of-sight visibility.

h1 = 100;
vis = los2(Z,R,lat1,lon1,lat2,lon2,h1)

vis = logical
   0

Calculate visibility information for the intermediate points. The outputs lattrk and lontrk contain the latitude and longitude coordinates of the intermediate points. The output visprofile indicates whether the intermediate points are visible from South Boulder Peak.

[~,visprofile,~,~,lattrk,lontrk] = los2(Z,R,lat1,lon1,lat2,lon2,100);

Create a geographic globe that uses custom terrain for the area around South Boulder Peak.

addCustomTerrain("southboulder","n39_w106_3arc_v2.dt1")
uif = uifigure;
g = geoglobe(uif,"Terrain","southboulder");

Plot the line of sight from South Boulder Peak to the nearby point. Use a magenta line to indicate the point is not visible from above the peak.

geoplot3(g,[lat1 lat2],[lon1 lon2],[h1 0],"m","LineWidth",2, ...
    "HeightReference","terrain")

Plot the intermediate points. Use magenta markers for points that are not visible and green markers for points that are visible. Plot each value 10 meters above the terrain so the markers are not obscured by the terrain.

hold(g,"on")
geoplot3(g,lattrk(~visprofile),lontrk(~visprofile),10, ...
    "mo","MarkerSize",2,"LineWidth",2,"HeightReference","terrain")
geoplot3(g,lattrk(visprofile),lontrk(visprofile),10,"go", ...
    "MarkerSize",2,"LineWidth",2,"HeightReference","terrain")

Adjust the view by setting the camera position, pitch, roll, and heading.

campos(g,39.9519,-105.3039,2.9424e+03)
campitch(g,-31.7850)
camroll(g,0.3603)
camheading(g,36.5618)

Close the figure containing the geographic globe and remove the custom terrain.

close(uif)
removeCustomTerrain("southboulder")

Input Arguments

Z — Elevation data grid

m-by-n array

Elevation data grid, in meters, specified as an m-by-n array.

Data Types: single | double

R — Spatial reference for Z

GeographicCellsReference object | GeographicPostingsReference object

Spatial reference for Z, specified as a GeographicCellsReference or GeographicPostingsReference object. The RasterSize property of R must be consistent with size(Z).

lat1 — Latitude of first point in degrees

scalar | vector

Latitude of the first point in degrees, specified as a scalar or vector.

The sizes of lat1, lon1, lat2, and lon2 must match.

Data Types: single | double

lon1 — Longitude of first point

scalar | vector

Longitude of the first point, in degrees, specified as a scalar or vector.

The sizes of lat1, lon1, lat2, and lon2 must match.

Data Types: single | double

lat2 — Latitude of second point

scalar | vector

Latitude of the second point, in degrees, specified as a scalar or vector.

The sizes of lat1, lon1, lat2, and lon2 must match.

Data Types: single | double

lon2 — Longitude of second point

scalar | vector

Longitude of the second point, in degrees, specified as a scalar or vector.

The sizes of lat1, lon1, lat2, and lon2 must match.

Data Types: single | double

h1 — Height of first point

0 (default) | scalar | vector

Height of the first point, in meters, specified as a scalar or vector.

The size of h1 must match the size of lat1 and lon1.

Data Types: single | double

h2 — Height of second point

0 (default) | scalar | vector

Height of the second point, in meters, specified as a scalar or vector.

The size of h2 must match the size of lat2 and lon2.

Data Types: single | double

h1ref — Height reference for first point

"AGL" (default) | "MSL"

Height reference for the first point, specified as one of these options:

• "AGL" — Reference h1 to the terrain (ground level).

• "MSL" — Reference h1 to the sphere (mean sea level).

Data Types: char | string

h2ref — Height reference for second point

"AGL" (default) | "MSL"

Height reference for the second point, specified as one of these options:

• "AGL" — Reference h2 to the terrain (ground level).

• "MSL" — Reference h2 to the sphere (mean sea level).

Data Types: char | string

rad — Radius of reference sphere

6371000 (default) | positive scalar

Radius of the reference sphere, in meters, specified as a positive scalar.

Data Types: single | double

effectiveRad — Effective radius of reference sphere

positive scalar

Effective radius of the reference sphere, in meters, specified as a positive scalar.

This argument enables you to account for the curvature of signal paths due to refraction in the atmosphere. For example, you can treat radio propagation in the atmosphere as straight-line propagation on a sphere with 4/3 the radius of the Earth by specifying rad as 6371000 and effectiveRad as 4/3*6371000.

To calculate line-of-sight visibility for a flat Earth, specify this argument as Inf.

If you do not specify this argument, then the function uses the value of rad.

Data Types: single | double

Output Arguments

vis — Indicator for visibility between first and second points

logical scalar | logical vector

Indicator for visibility between the first and second points, returned as a logical scalar or a logical array. The size of vis matches the size of lat1.

• A logical 1 (true) indicates that the first point has line-of-sight visibility with the corresponding second point.

• A logical 0 (false) indicates that the line of sight between the first point and corresponding second point is obscured by terrain.

visprofile — Indicator for visibility between first point and intermediate points

logical vector | cell array of logical vectors

Indicator for visibility between the first point and intermediate points, returned as a logical vector or a cell array of logical vectors.

• A logical 1 (true) indicates that the first point has line-of-sight visibility with that intermediate point.

• A logical 0 (false) indicates that the line of sight between the first point and that intermediate point is obscured by terrain.

The function returns a logical vector when lat1, lon1, lat2, and lon2 are scalars. The function returns a cell array of logical vectors when lat1, lon1, lat2, and lon2 are vectors. The number of cells within the cell array matches the size of lat1.

dist — Distance from first point to intermediate point

numeric vector | cell array of numeric vectors

Distance from the first point to the intermediate point, in meters, returned as a numeric vector or a cell array of numeric vectors.

The function returns a numeric vector when lat1, lon1, lat2, and lon2 are scalars. The function returns a cell array of numeric vectors when lat1, lon1, lat2, and lon2 are vectors. The number of cells within the cell array matches the size of lat1.

h — Height of intermediate points

numeric vector | cell array of numeric vectors

Height of intermediate points, in meters, returned as a numeric vector or a cell array of numeric vectors.

The function returns a numeric vector when lat1, lon1, lat2, and lon2 are scalars. The function returns a cell array of numeric vectors when lat1, lon1, lat2, and lon2 are vectors. The number of cells within the cell array matches the size of lat1.

lattrk — Latitude of intermediate points

numeric vector | cell array of numeric vectors

Latitude of intermediate points, in degrees, returned as a numeric vector or a cell array of numeric vectors.

The function returns a numeric vector when lat1, lon1, lat2, and lon2 are scalars. The function returns a cell array of numeric vectors when lat1, lon1, lat2, and lon2 are vectors. The number of cells within the cell array matches the size of lat1.

lontrk — Longitude of intermediate points

numeric vector | cell array of numeric vectors

Longitude of intermediate points, in degrees, returned as a numeric vector or a cell array of numeric vectors.

The function returns a numeric vector when lat1, lon1, lat2, and lon2 are scalars. The function returns a cell array of numeric vectors when lat1, lon1, lat2, and lon2 are vectors. The number of cells within the cell array matches the size of lat1.

Version History

Introduced before R2006a

R2024b: los2 does not accept referencing vectors or referencing matrices as input

The los2 function does not accept referencing vectors or referencing matrices as input. Use a geographic raster reference object, specified as a GeographicCellsReference or GeographicPostingsReference object, as input instead. Reference objects have several advantages over referencing vectors and referencing matrices.

• Unlike referencing vectors and referencing matrices, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns.

• You can manipulate the limits of geographic rasters associated with reference objects using the geocrop function.

• You can manipulate the size and resolution of geographic rasters associated with reference objects using the georesize function.

To update your code, create a geographic reference object.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing vector to a geographic reference object by using the refvecToGeoRasterReference function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

R2023b: los2 will not accept referencing vectors or referencing matrices as input

When you specify a referencing vector or referencing matrix as input, the los2 function issues a warning that it will not accept referencing vectors or referencing matrices as input in a future release.