Main Content

areamat

Surface area covered by nonzero values in binary data grid

Syntax

A = areamat(BW,R)
A = areamat(BW,R,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 = (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.

Examples

collapse all

Find the surface area in normalized units of the part of Earth's terrain that is above sea level.

First, load elevation raster data and a geographic cells reference object. The raster contains terrain heights relative to mean sea level. Then, create a logical array representing the terrain above sea level.

load topo60c
topoASL = topo60c > 0;

Find the surface area in normalized units of the elements of the array that contain true.

areamat(topoASL,topo60cR)
ans = 0.2890

The result means 28.9% of Earth's terrain is above sea level.

Find the surface area in kilometers of the part of Earth's terrain that is above sea level.

First, load elevation raster data and a geographic cells reference object. The raster contains terrain heights relative to mean sea level. Then, create a reference sphere for Earth and specify its units as kilometers.

load topo60c
s = referenceSphere('earth','km');

Create a logical array representing the terrain above sea level.

topoASL = topo60c > 0;

Find the surface area in kilometers of the elements of the array that contain true.

areamat(topoASL,topo60cR,s)
ans = 1.4739e+08

The result means that approximately 147 million square kilometers of Earth's terrain is above sea level.

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

See Also

|

Introduced before R2006a