Geomorphon Landforms (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Calculates the geomorphon pattern of each cell of an input surface raster and classifies calculated geomorphons into common landform types.

Usage

• A geomorphon is a representation of landscape based on elevation differences within the surrounding area of a target cell. A total of 498 unique geomorphon patterns can be classified into 10 common landform types: flat, peak, ridge, shoulder, spur, slope, hollow, footslope, valley, and pit (Jasiewicz and Stepiski, 2012).

• The Output landforms raster (out_landforms_raster in Python) parameter value is the primary output. This is a raster representing the result of the geomorphon classification into 10 landform types using a lookup table. The geomorphon pattern is an optional output and can be saved by specifying the Output geomorphons raster (out_geomorphons_raster in Python) parameter value. This is a raster representing the unique identifier of the geomorphon pattern. It can be used to classify geomorphons into landforms other than those in the Output landforms raster value.

• The surrounding area, the analysis area, of a target cell is determined by the Search distance (search_distance in Python) and Skip distance (skip_distance in Python) parameters. These parameters define the radius of the area that will be used to calculate the geomorphon pattern of a target cell. The Skip distance parameter specifies the distance away from the target cell where the analysis area starts. The Search distance parameter specifies where the area extends to. The Skip distance parameter value must be smaller than the Search distance parameter value.

• When a large value is used for the Search distance parameter, the result is a large analysis area, which may provide more information about the surrounding terrain and improve the ability to classify a target cell as part of a large landscape feature. At the same time, a large value may omit small landscape features. For example, a cell may be classified as flat in a small analysis area (a small Search distance value) but may be classified as a valley in a broader analysis area (a large Search distance value). Smaller values of the Search distance parameter will result in small analysis areas where large landscape features may be broken into smaller features and classified accordingly.

• Specifying a value for the Skip distance parameter results in a targeted focus to areas farther away from the target cell and generates a smoother classified landforms raster. If no Skip distance value is specified, all neighboring cells within the analysis area will be considered when identifying the geomorphon pattern.

• The Flat terrain angle threshold (angle_threshold in Python) parameter specifies the difference between the line-of-sight angles below which the visible surrounding area will be considered flat. When determining the Flat terrain angle threshold parameter value, consider the cell size of the Input surface raster parameter value. For example, a 1 degree difference means several meters of elevation difference for an input raster with a large cell size. A large Flat terrain angle threshold parameter value will result in more areas identified as flat.

• Specifying the Z unit (z_unit in Python) value ensures proper computation of elevation differences and line-of-sight angles that are used to generate the geomorphon pattern and landform classification.

  If a z unit is available in the vertical coordinate system of the input raster, it will be applied automatically. It is recommended that you define a z unit for the input raster if it is missing in the input surface raster. You can use the Define Projection tool to specify a z unit. If a vertical coordinate is undefined, meters will be used by default. This tool will produce a warning when the specified z unit is incorrect based on the calculation of line-of-sight angles on each cardinal direction. For example, if the DEM elevation values are in meters but centimeters have been specified for the Z unit parameter, the terrain will be considered flat, and landforms will not be classified correctly.

• NoData cells in the surface raster will be ignored and those cells will be assigned NoData in the Output landforms raster and Output geomorphons raster parameter values.

• References:

  • Jasiewicz, J and Stepinski, T. J., Geomorphons - a pattern recognition approach to classification and mapping of landforms, Geomorphology, 182, January 15, 2013: 147-56. https://doi.org/10.1016/j.geomorph.2012.11.005

Parameters

Dialog

Label	Explanation	Data Type
Input surface raster	The input surface raster.	Raster Layer
Output geomorphons raster (Optional)	Each geomorphon pattern will be assigned a unique identifier, which is stored for each cell in the output geomorphons raster. The output is of integer type.	Raster Dataset
Flat terrain angle threshold (Optional)	The angle threshold (in degrees) below which the target cell will be classified as flat. The default value is 1 degree. Specifying a larger value than the default is recommended for low resolution DEMs.	Double
Distance units (Optional)	Specifies the distance unit that will be used for the Search distance and Skip distance parameters. Distance will be measured in the specified unit or number of cells. The default is Cells. Cells—The distance unit will be cells. Meters—The distance unit will be meters. Centimeters—The distance unit will be centimeters. Kilometers—The distance unit will be kilometers. Inches—The distance unit will be inches. Feet—The distance unit will be feet. Yard—The distance unit will be yards. Miles—The distance unit will be miles.	String
Search distance (Optional)	The distance away from the target cell that defines the radius of the area that will be used to identify the geomorphon pattern. The default value is 10. Use a search distance value that matches the type and size of the landforms that you want to classify.	Double
Skip distance (Optional)	The distance away from the target cell where the analysis area starts. Neighboring cells that fall within this distance will be skipped and won't contribute to identification of the geomorphon pattern. The classification of each individual cell is determined by assessing the neighboring cells within the skip distance from the target cell center.	Double
Z unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If a vertical coordinate system does not exist, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. Inch—The linear unit will be inches. Foot—The linear unit will be feet. Yard—The linear unit will be yards. Mile US—The linear unit will be miles. Nautical mile—The linear unit will be nautical miles. Millimeter—The linear unit will be millimeters. Centimeter—The linear unit will be centimeters. Meter—The linear unit will be meters. Kilometer—The linear unit will be kilometers. Decimeter—The linear unit will be decimeters.	String

Return Value

Label	Explanation	Data Type
Output landforms raster	The output classified landforms raster. The output is of integer type. Each value corresponds to a specific landform type: Flat—cell value 1, Peak—cell value 2, Ridge—cell value 3, Shoulder—cell value 4, Spur—cell value 5, Slope—cell value 6, Hollow—cell value 7, Footslope—cell value 8, Valley—cell value 9, Pit—cell value 10.	Raster

Python

GeomorphonLandforms(in_surface_raster, {out_geomorphons_raster}, {angle_threshold}, {distance_units}, {search_distance}, {skip_distance}, {z_unit})

Name	Explanation	Data Type
in_surface_raster	The input surface raster.	Raster Layer
out_geomorphons_raster (Optional)	Each geomorphon pattern will be assigned a unique identifier, which is stored for each cell in the output geomorphons raster. The output is of integer type.	Raster Dataset
angle_threshold (Optional)	The angle threshold (in degrees) below which the target cell will be classified as flat. The default value is 1 degree. Specifying a larger value than the default is recommended for low resolution DEMs.	Double
distance_units (Optional)	Specifies the distance unit that will be used for the Search distance and Skip distance parameters. Distance will be measured in the specified unit or number of cells. The default is Cells. Specifies the distance unit that will be used for the search_distance and skip_distance parameters. Distance will be measured in the specified unit or number of cells. The default is CELLS. CELLS—The distance unit will be cells. METERS—The distance unit will be meters. CENTIMETERS—The distance unit will be centimeters. KILOMETERS—The distance unit will be kilometers. INCHES—The distance unit will be inches. FEET—The distance unit will be feet. YARDS—The distance unit will be yards. MILES—The distance unit will be miles.	String
search_distance (Optional)	The distance away from the target cell that defines the radius of the area that will be used to identify the geomorphon pattern. The default value is 10. Use a search distance value that matches the type and size of the landforms that you want to classify.	Double
skip_distance (Optional)	The distance away from the target cell where the analysis area starts. Neighboring cells that fall within this distance will be skipped and won't contribute to identification of the geomorphon pattern. The classification of each individual cell is determined by assessing the neighboring cells within the skip distance from the target cell center.	Double
z_unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If a vertical coordinate system does not exist, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. INCH—The linear unit will be inches. FOOT—The linear unit will be feet. YARD—The linear unit will be yards. MILE_US—The linear unit will be miles. NAUTICAL_MILE—The linear unit will be nautical miles. MILLIMETER—The linear unit will be millimeters. CENTIMETER—The linear unit will be centimeters. METER—The linear unit will be meters. KILOMETER—The linear unit will be kilometers. DECIMETER—The linear unit will be decimeters.	String

Return Value

Name	Explanation	Data Type
out_landforms_raster	The output classified landforms raster. The output is of integer type. Each value corresponds to a specific landform type: Flat—cell value 1, Peak—cell value 2, Ridge—cell value 3, Shoulder—cell value 4, Spur—cell value 5, Slope—cell value 6, Hollow—cell value 7, Footslope—cell value 8, Valley—cell value 9, Pit—cell value 10.	Raster

Code sample

GeomorphonLandforms example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

This example generates a landforms raster from an input surface raster using the default values for all optional parameters.

from arcpy.sa import *
outGeomorphonLandforms = GeomorphonLandforms("elevation_1m.tif", "", "", "", "", "", "")
outGeomorphonLandforms.save("C:/sapyexamples/output/outgeorphonlandforms01.tif")

GeomorphonLandforms example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

This example generates a landforms raster classified from geomorphons calculated over a search distance of 50 meters, skipping cells within 2 meters of the target cell.

# Name: GeomorphonLandforms_standalone.py
# Description: Calculates geomorphons over a search distance of 50 meters, skipping cells within 2 meters
# of the target cell. Terrain is considered flat if the difference between elevation angles is less or equal to 2 degrees.
# The calculated geomorphons are classified into landforms and saved as a raster. 
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy.sa import *

# Set environment settings
arcpy.env.workspace = "C:/sapyexamples/data"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Set local variables
inRaster = "elevation_1m.tif"
inAngleThreshold = 2
inDistanceUnits = "METERS"
inSearchDistance = 50
inSkipDistance = 2
inZunit = "METER"

# Execute the tool
outGeomorphonLandforms = GeomorphonLandforms(inRaster, "", inAngleThreshold, inDistanceUnits,
                                         inSearchDistance, inSkipDistance, inZunit)

# Save the output 
outGeomorphonLandforms.save("C:/sapyexamples/output/outgeomorphonlandforms02.tif")

Environments

Cell Size, Cell Size Projection Method, Current Workspace, Output Coordinate System, Extent, Mask, Snap Raster