Surface area covered by nonzero values in binary data grid

`A = areamat(BW,R)`

A = areamat(BW,refvec,ellipsoid)

[A, cellarea] = areamat(...)

`A = areamat(BW,R)`

returns the surface area
covered by the elements of the binary regular data grid `BW`

,
which contain the value 1 (`true`

). `BW`

can
be the result of a logical expression such as ```
BW = (topo
> 0)
```

. `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(BW)`

and
its `RasterInterpretation`

must be `'cells'`

.

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.

The output `A`

expresses surface area as a
fraction of the surface area of the unit sphere (4*pi), so the result
ranges from 0 to 1.

`A = areamat(BW,refvec,ellipsoid)`

calculates the surface area on the
ellipsoid or sphere defined by the input `ellipsoid`

, which can be a
`referenceSphere`

, `referenceEllipsoid`

, or `oblateSpheroid`

object, or a vector of the form ```
[semimajor_axis
eccentricity]
```

. The units of the output, `A`

, are the
square of the length units in which the semimajor axis is provided. For example, if
`ellipsoid`

is replaced with
`wgs84Ellipsoid('kilometers')`

, then `A`

is in
square kilometers.

`[A, cellarea] = areamat(...)`

returns a
vector, `cellarea`

, describing the area covered by
the data cells in `BW`

. Because all the cells in
a given row are exactly the same size, only one value is needed per
row. Therefore `cellarea`

has size `M-by-1`

,
where `M = size(BW,1)`

is the number of rows in `BW`

.

load topo area = areamat((topo>127),topolegend) area = 0.2411

Approximately 24% of the Earth has an altitude greater than 127 meters. The surface area of this portion of the Earth in square kilometers if a spherical ellipsoid is:

earth = referenceSphere('earth', 'km'); area = areamat((topo>127),topolegend,earth) area = 1.2299e+08

To illustrate the `cellarea`

output, consider
a smaller map:

BW = ones(9,18); refvec = [.05 90 0] % each cell 20x20 degrees [area,cellarea] = areamat(BW,refvec) area = 1.0000 cellarea = 0.0017 0.0048 0.0074 0.0091 0.0096 0.0091 0.0074 0.0048 0.0017

Each entry of `cellarea`

represents the portion
of the unit sphere's total area a cell in that row of `BW`

would
contribute. Since the column extends from pole to pole in this case,
it is symmetric.

Given a regular data grid that is a logical 0-1 matrix, the `areamat`

function
returns the area corresponding to the true, or 1, elements. The input
data grid can be a logical statement, such as `(topo>0)`

,
which is 1 everywhere that `topo`

is greater than
0 meters, and 0 everywhere else. This is an illustration of that matrix:

This calculation is based on the `areaquad`

function
and is therefore limited only by the granularity of the cellular data.