Accelerating the pace of engineering and science

# areamat

Surface area covered by nonzero values in binary data grid

## Syntax

A = areamat(BW,R)
A = areamat(BW,refvec,ellipsoid)
[A, cellarea] = areamat(...)

## Description

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.

## Examples

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