# viewshed

Areas visible from point on terrain elevation grid

## Syntax

`[vis,R] = viewshed(Z,R,lat1,lon1)`

viewshed(Z,R,lat1,lon1,observerAltitude)

viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude)

viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...

observerAltitudeOption)

viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...

observerAltidueOption,targetAltitudeOption)

viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...

observerAltitudeOption,targetAltitudeOption,actualRadius)

viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...

observerAltitudeOption,targetAltitudeOption,
...

actualRadius,effectiveRadius)

## Description

`[vis,R] = viewshed(Z,R,lat1,lon1)`

computes
areas visible from a point on a digital elevation grid. `Z`

is
a regular data grid containing elevations in units of meters. The
observer location is provided as scalar latitude and longitude in
units of degrees. The visibility grid `vis`

contains `1`

s
at the surface locations visible from the observer location, and `0`

s
where the line of sight is obscured by terrain. `R`

can
be a geographic raster reference object, a referencing vector, or
a referencing matrix.

If `R`

is a geographic raster reference object,
its `RasterSize`

property must be consistent with `size(Z)`

.

If `R`

is a referencing vector, it must be
a 1-by-3 with elements:

[cells/degree northern_latitude_limit western_longitude_limit]

If `R`

is a referencing matrix, it must be
3-by-2 and transform raster row and column indices to or from geographic
coordinates according to:

[lon lat] = [row col 1] * R

If `R`

is a referencing matrix, it must define
a (non-rotational, non-skewed) relationship in which each column of
the data grid falls along a meridian and each row falls along a parallel.
Nearest-neighbor interpolation is used by default. NaN is returned
for points outside the grid limits or for which `lat`

or `lon`

contain
NaN. All angles are in units of degrees.

`viewshed(Z,R,lat1,lon1,observerAltitude)`

places
the observer at the specified altitude in meters above the surface.
This is equivalent to putting the observer on a tower. If omitted,
the observer is assumed to be on the surface.

`viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude)`

checks for visibility of target points a specified distance above the terrain. This is
equivalent to putting the target points on towers that do not obstruct the view. If
omitted, the target points are assumed to be on the surface.

```
viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...
```

controls
whether the observer is at a relative or absolute altitude. If the

observerAltitudeOption)`observerAltitudeOption`

is `'AGL'`

,
then `observerAltitude`

is in meters above ground
level. If `observerAltitudeOption`

is `'MSL'`

, `observerAltitude`

is
interpreted as altitude above zero, or mean sea level. If omitted, `'AGL'`

is
assumed.

```
viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...
```

controls
whether the target points are at a relative or absolute altitude.
If the target altitude option is

observerAltidueOption,targetAltitudeOption)`'AGL'`

, the `targetAltitude`

is
in meters above ground level. If `targetAltitudeOption`

is `'MSL'`

, `targetAltitude`

is
interpreted as altitude above zero, or mean sea level. If omitted, `'AGL'`

is
assumed.

```
viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...
```

does
the visibility calculation on a sphere with the specified radius.
If omitted, the radius of the earth in meters is assumed. The altitudes,
the elevations, and the radius should be in the same units. This calling
form is most useful for computations on bodies other than the Earth.

observerAltitudeOption,targetAltitudeOption,actualRadius)

```
viewshed(Z,R,lat1,lon1,observerAltitude,targetAltitude,
...
```

assumes
a larger radius for propagation of the line of sight. This can account
for the curvature of the signal path due to refraction in the atmosphere.
For example, radio propagation in the atmosphere is commonly treated
as straight line propagation on a sphere with 4/3 the radius of the
Earth. In that case the last two arguments would be

observerAltitudeOption,targetAltitudeOption,
...

actualRadius,effectiveRadius)`R_e`

and `4/3*R_e`

,
where `R_e`

is the radius of the earth. Use `Inf`

for
flat Earth `viewshed`

calculations. The altitudes,
the elevations, and the radii should be in the same units.

## Examples

## Tips

The observer should be located within the latitude-longitude
limits of the elevation grid. If the observer is located outside the
grid, there is insufficient information to calculate a viewshed.
In this case `viewshed`

issues a warning and sets
all elements of `vis`

to zero.

## Version History

**Introduced before R2006a**