# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

To view all translated materials including this page, select Japan from the country navigator on the bottom of this page.

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

## Tips

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.