viewshed

Visible area from point on or above terrain

Syntax

[vis,visR] = viewshed(Z,R,latObs,lonObs)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef,rad)

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef,rad,effectiveRad)

Description

Specify Coordinates and Heights

[vis,visR] = viewshed(Z,R,latObs,lonObs) calculates the visible area (the viewshed) for the point specified by latObs and lonObs. Specify spatially referenced terrain data, in meters, using Z and R. This function assumes that the Earth is a sphere.

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs) specifies the height, in meters, of the observer.

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget) specifies the height, in meters, of the target points. The target points are all the points specified by the spatial reference.

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef) references the height of the observer to either the terrain (ground level) or the sphere (mean sea level).

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef) references the height of the target points to either the terrain (ground level) or the sphere (mean sea level).

Specify Reference Sphere

[vis,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef,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,visR] = viewshed(Z,R,latObs,lonObs,hObs,hTarget,hObsRef,hTargetRef,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.

Examples

Display Viewshed for Point on Terrain

Create sample terrain data by using the peaks and georefcells functions.

Z = 500*peaks(100);
R = georefcells([-0.1 0],[0 0.1],size(Z));

Calculate the viewshed for a sample point that is 200 meters above the terrain.

latObs = -0.027;
lonObs = 0.05;
[vis,visR] = viewshed(Z,R,latObs,lonObs);

Display the viewshed as a surface on an axesm-based map. Plot the sample point so that it appears above the terrain.

figure
axesm("globe","geoid",earthRadius)
meshm(vis,visR,size(Z),Z)
axis tight
camposm(-10,-10,1e6)
camupm(0,0)

[row,col] = geographicToDiscrete(R,latObs,lonObs);
h = Z(row,col);
plot3m(latObs,lonObs,h+200,"ko","MarkerSize",7,"MarkerFaceColor","r")

Adjust the colormap and lighting. Add a colorbar.

colormap(flipud(summer(2))) 
brighten(0.75)
shading interp
camlight

cb = lcolorbar(["Obscured" "Visible"]);
cb.Position = [0.85 0.5 0.02 0.1];

Display Viewshed for Point Above Terrain

Display the area that is visible by radar for an aircraft flying above the terrain. You can use the viewshed function to model radio wave propagation in the atmosphere as straight lines on a sphere.

Load terrain elevation data for an area around the Korean peninsula. To make the water areas appear consistent on the plot, set all elevations below sea level (korea5c<0) to the same value.

load korea5c
korea5c(korea5c<0) = -1;

Specify the location of the aircraft. Then, calculate visible areas for the aircraft, at 3000 meters above mean sea level, of the surface. Model radio propagation in the atmosphere by specifying an effective radius for the reference sphere.

latObs = 34.0931;
lonObs = 125.6578; 
hObs = 3000;
hTarget = 0;
rad = earthRadius;
[vis1,vis1R] = viewshed(korea5c,korea5cR,latObs,lonObs,hObs,hTarget,"MSL","AGL",rad,4/3*rad);

Set up a relief map for the area by adjusting the data aspect ratio, the plot box aspect ratio, and the lighting.

figure
worldmap(korea5c,korea5cR)
setm(gca,"geoid",[1 0])

da = daspect;
pba = pbaspect;
da(3) = 7.5*pba(3)/da(3);
daspect(da);

camlight(90,5)
camlight(0,5)
material([0.25 0.8 0])

Display the terrain data, the viewshed, and the aircraft on the map. Adjust the colormap so that the visible areas appear in blue and the obscured areas appear in red. Note that some ocean areas are obscured by an island.

meshm(vis1,vis1R,size(korea5c),korea5c)
plotm(latObs,lonObs,"ko","MarkerFaceColor","k")
colormap([1 0 0; 0 0 1])

Calculate the viewshed again, this time calculating visible areas for the aircraft at 3000 meters of other aircraft flying above it at 5000 meters. The visible area is larger, with some of the area obscured by the island and mountains.

hTarget = 5000;
[vis2,vis2R] = viewshed(korea5c,korea5cR,latObs,lonObs,hObs,hTarget,"MSL","MSL",rad,4/3*rad);
clmo surface
meshm(vis2,vis2R,size(korea5c),korea5c)

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

latObs — Latitude of observer

scalar

Latitude of the observer, in degrees, specified as a scalar.

If the latitude is outside the latitude limits of R, then the viewshed function issues a warning and sets all elements of vis to 0. You can find the latitude limits of R by querying its LatitudeLimits property.

Data Types: single | double

lonObs — Longitude of observer

scalar

Longitude of the observer, in degrees, specified as a scalar.

If the longitude is outside the latitude limits of R, then the viewshed function issues a warning and sets all elements of vis to 0. You can find the longitude limits of R by querying its LongitudeLimits property.

Data Types: single | double

hObs — Height of observer

0 (default) | scalar

Height of the observer, in meters, specified as a scalar.

Data Types: single | double

hTarget — Height of target points

0 (default) | scalar

Height of the target points, in meters, specified as a scalar.

Data Types: single | double

hObsRef — Height reference for observer

"AGL" (default) | "MSL"

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

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

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

Data Types: char | string

hTargetRef — Height reference for target points

"AGL" (default) | "MSL"

Height reference for the target points, specified as one of these options:

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

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

Data Types: char | string

rad — Radius of reference sphere in meters

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 in meters

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 — Visibility indicator

m-by-n array containing 0 and 1 values

Visibility indicator, returned as an m-by-n array containing 0 and 1 values. The size of vis matches the size of Z.

• A value of 1 indicates that the observer has line-of-sight visibility with the target point.

• A value of 0 indicates that the line of sight between the observer and the target point is obscured by terrain.

visR — Spatial reference for vis

GeographicCellsReference object | GeographicPostingsReference object

Spatial reference for vis, returned as a GeographicCellsReference or GeographicPostingsReference object.

The output visR is equivalent to the input R.

Version History

Introduced before R2006a

R2022b: viewshed will not accept referencing vectors or referencing matrices as input

The viewshed function will not accept referencing vectors or referencing matrices as input in a future release. 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.