Main Content

Surface area covered by nonzero values in binary data grid

`A = areamat(BW,R)`

A = areamat(BW,R,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 = (topo60c > 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,R,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. If you do not specify `ellipsoid`

and
`R`

is a reference object with a non-empty
`GeographicCRS`

property, then `areamat`

uses
the ellipsoid contained in the `Spheroid`

property of the
`geocrs`

object in the `GeographicCRS`

property of
`R`

.

`[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`

.

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 `(topo60c > 0)`

, which is 1
everywhere that `topo60c`

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.