Skip to content

r.cell.area

Calculates the area of each raster cell for the computational region

r.cell.area output=name units=string [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.cell.area output=name units=m2

grass.tools.Tools.r_cell_area(output, units, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_cell_area(output="name", units="m2")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.run_command("r.cell.area", output, units, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.cell.area", output="name", units="m2")

Parameters

output=name [required]
    Output raster of cell areas
    Name of output raster map containing cell areas
units=string [required]
    Output units
    Units for output cell areas
    Allowed values: m2, km2, ha, acres, mi2
    m2: Square meters
    km2: Square kilometers
    ha: Hectares
    acres: Acres
    mi2: Square miles
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Output raster of cell areas
    Name of output raster map containing cell areas
    Used as: output, raster, name
units : str, required
    Output units
    Units for output cell areas
    Allowed values: m2, km2, ha, acres, mi2
    m2: Square meters
    km2: Square kilometers
    ha: Hectares
    acres: Acres
    mi2: Square miles
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

Raises:

grass.tools.ToolError: When the tool ended with an error.

output : str, required
    Output raster of cell areas
    Name of output raster map containing cell areas
    Used as: output, raster, name
units : str, required
    Output units
    Units for output cell areas
    Allowed values: m2, km2, ha, acres, mi2
    m2: Square meters
    km2: Square kilometers
    ha: Hectares
    acres: Acres
    mi2: Square miles
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

r.cell.area is deprecated. Use the built-in area() function in r.mapcalc instead (available since GRASS 7.4). It provides an ellipsoidal cell-area calculation and requires no extra module.

r.cell.area computes the area of each raster cell in the current computational region and writes the result to a new raster map. It is now a thin wrapper around the area() function in r.mapcalc and emits a deprecation warning on every run.

NOTES

The area() function in r.mapcalc returns cell area in square metres using an ellipsoidal model. Multiply by a constant to obtain other units:

r.cell.area units Equivalent r.mapcalc expression
m2 r.mapcalc "output = area()"
km2 r.mapcalc "output = area() * 1e-6"
ha r.mapcalc "output = area() * 1e-4"
acres r.mapcalc "output = area() / 4046.8564224"
mi2 r.mapcalc "output = area() / 2589988.110336"

EXAMPLES

Compute cell area in square metres (recommended, no module needed):

r.mapcalc "cell_area_m2 = area()"

Compute cell area in hectares:

r.mapcalc "cell_area_ha = area() * 1e-4"

Using r.cell.area (deprecated, emits a warning):

r.cell.area output=cell_area units=ha

SEE ALSO

r.mapcalc

AUTHOR

Andrew D. Wickert