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.

More About

expand all

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.

See Also

|

Was this topic helpful?