Surface Parameters (Spatial Analyst)

Available with Spatial Analyst license.

Available with 3D Analyst license.

Summary

Determines parameters of a raster surface such as aspect, slope and curvatures.

Learn more about how Surface Parameters works.

Usage

• The output parameters are calculated on a cell-by-cell basis, by fitting a local surface around a target cell. Five surface parameters can be calculated: Slope, Aspect, Mean curvature, Tangential (normal contour) curvature, and Profile (normal slope line) curvature. These options are available in the Parameter type parameter (parameter_type in Python).

• All output parameters are calculated using geodesic coordinates and equations.

• When the Slope (SLOPE in Python) option is specified for the Parameter type, the output represents the rate of change of elevation for each digital elevation model (DEM) cell. It is the first derivative of a DEM. The range of values from the slope output depends on the type of measurement units.

• When the Aspect (ASPECT in Python) option is specified for the Parameter type, the output identifies the compass direction that the downhill slope faces for each location. It is expressed in positive degrees from 0 to 360, measured clockwise from north.

• Curvature is used to describe the shape of a surface. When applied to earth science, it is used to help understand the impacts of gravity, erosion and other forces upon the surface, and is used in conjunction with other surface parameters to identify and classify landforms.

  • The Mean curvature (MEAN_CURVATURE in Python) measures the overall curvature of the surface. It is computed as the average of the minimum and maximum curvature. When this is specified for the Parameter type, the output is equivalent to mean of profile (normal slope line) and tangential (normal contour) curvatures. Its sign, positive or negative, is not a definitive indicator except at extreme values. High positive values indicate areas of maximum denudation, and high negative values indicate areas of maximum accumulation (Minár et al., 2020).
  • The Profile (normal slope line) curvature (PROFILE_CURVATURE in Python) measures the geometric normal curvature along the slope line. Positive values indicate areas of acceleration of surface flow and erosion. Negative profile curvature indicates areas of slowing surface flow and deposition. A positive profile (normal slope line) curvature indicates the surface is convex at that cell in the direction of the slope. A negative curvature indicates the surface is concave at that cell in that same direction. A value of 0 indicates the surface is flat.
  • The Tangential (normal contour) curvature (TANGENTIAL_CURVATURE in Python) measures the geometric normal curvature perpendicular to the slope line, tangent to the contour line. Positive values indicate areas of diverging surface flow. Negative tangential curvatures indicates areas of converging surface flow. A positive tangential (normal contour) curvature indicates the surface is convex at that cell perpendicular to the direction of the slope. A negative curvature indicates the surface is concave at that cell in the direction perpendicular to the slope. A value of 0 indicates the surface is flat.

  The units of all three curvature type outputs will be the reciprocal of the xy units of the Output Coordinate System.

• The Quadratic (QUADRATIC in Python) option in Local surface type (local_surface_type in Python) does not fit the neighborhood cells exactly. This is the default, and recommended option for most data and applications.

  • The quadratic surface minimizes the effect of noisy surface data such as a high resolution lidar surface, which is especially important when computing curvature.
  • The quadratic surface should be used when specifying a neighborhood size that is larger than the cell size, and when using the adaptive neighborhood option.

• The Biquadratic (BIQUADRATIC in Python) option in Local surface type fits the data from the neighborhood cells exactly.

  • This option is suitable for a highly accurate input surface.
  • If the neighborhood distance is larger than the input raster cell size, the accuracy advantages of the biquadratic surface type will be lost. The neighborhood distance should be left as the default (equal to the cell size).

• The Neighborhood distance (neighborhood_distance in Python) determines the neighborhood size, and calculates the surface parameter over this distance from the target cell center.

  • It cannot be less than the input raster cell size.
  • A smaller neighborhood distance captures more local variability in the landscape, characteristics of smaller landscape features. With high resolution elevation data, larger distances may be more appropriate.

• If the Use adaptive neighborhood parameter is checked (use_adaptive_neighborhood is set to ADAPTIVE_NEIGHBORHOOD in Python), the neighborhood distance will change with variability in the terrain. The neighborhood distance will shrink if there is too much variability in the calculation window.

• Specifying the surface Z unit (z-unit in Python) is important to ensure the proper computation of the slope output.

  If a z-unit is available in the vertical coordinate system of the input raster, it will be applied automatically. It is suggested that you define a z-unit for the input raster if it is missing. You can use the Define Projection tool to specify a z-unit. If it is undefined, meter will be used by default.

• The range of values in the slope output depends on the type of Output slope measurement (output_slope_measurement in Python) units:

  • For Degrees (DEGREE in Python), the range of slope values is 0 to 90.
  • For Percent rise (PERCENT_RISE in Python), the range is 0 to essentially infinity. A flat surface is 0 percent, a 45 degree surface is 100 percent, and as the surface becomes more vertical, the percent rise becomes increasingly larger.

• If the Project geodesic azimuths parameter is checked (project_geodesic_azimuths is set to PROJECT_GEODESIC_AZIMUTHS in Python), the following are true:

  • North is always represented by 360 degrees.
  • Azimuths will be projected to correct the distortion caused by a nonconformal Output Coordinate System. These angles can be used to accurately locate points along the steepest downhill slope.

  Check the Project geodesic azimuths parameter if you're using the Surface Parameters output as a back direction input in the Input back direction or flow direction raster (in_back_direction_raster in Python) parameter for a tool in the Distance toolset.

• If the Use equatorial aspect parameter is checked (project_geodesic_azimuths is set to USE_EQUATORIAL_ASPECT in Python), aspect will be measured from a point along the equator, to correct for the skewing of direction that happens when approaching the poles. This option ensures that the North-South and East-West axes are perpendicular to each other.

  Check the Use equatorial aspect parameter if your terrain is near to the North or South Pole.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

• References:

  • James D.E., M.D. Tomer, S.A. Porter. (2014). Trans-scalar landform segmentation from high-resolution digital elevation models. Poster presented at: ESRI Annual Users Conference; July 2014; San Diego, California.
  • Minár, J., Evans, I. S., & Jenčo, M. (2020). A comprehensive system of definitions of land surface (topographic) curvatures, with implications for their application in geoscience modelling and prediction. Earth-Science Reviews, 103414. https://doi.org/10.1016/j.earscirev.2020.103414

Parameters

Dialog

Label	Explanation	Data Type
Input surface raster	The input surface raster.	Raster Layer
Parameter type (Optional)	Determines the output surface parameter type to compute. Slope —The rate of change in elevation. This is the default. Aspect —The downslope direction of the maximum rate of change for each cell. Mean curvature —Measures the overall curvature of the surface. It is computed as the average of the minimum and maximum curvature. This curvature describes the intrinsic convexity or concavity of the surface, independent of direction or gravity influence. Tangential (normal contour) curvature —Measures the geometric normal curvature perpendicular to the slope line, tangent to the contour line. This curvature is typically applied to characterize the convergence or divergence of flow across the surface. Profile (normal slope line) curvature —Measures the geometric normal curvature along the slope line. This curvature is typically applied to characterize the acceleration and deceleration of flow down the surface.	String
Local surface type (Optional)	Determines the type of surface function fitted around the target cell. Quadratic —Fits a quadratic surface function to the neighborhood cells. This is the default. Biquadratic —Fits a biquadratic surface function to the neighborhood cells.	String
Neighborhood distance (Optional)	The output is calculated over this distance from the target cell center. It determines the neighborhood size. The default value is the input raster cell size, resulting in a 3 x 3 neighborhood.	Linear Unit
Use adaptive neighborhood (Optional)	Allow neighborhood distance to vary with landscape changes. The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size. Unchecked—Use a single (fixed) neighborhood distance at all locations. This is the default. Checked—Use an adaptive neighborhood distance at all locations.	Boolean
Z unit (Optional)	The linear unit of vertical z-values. 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
Output slope measurement (Optional)	When Parameter type is Slope, determines the measurement units (degrees or percentages) of the output slope raster. Degree — The inclination of slope will be calculated in degrees. Percent rise — The inclination of slope will be calculated as percent rise, also referred to as the percent slope.	String
Project geodesic azimuths (Optional)	Specifies whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference. Unchecked—Geodesic azimuths will not be projected. This is the default. Checked—Geodesic azimuths will be projected.	Boolean
Use equatorial aspect (Optional)	Measure aspect from a point on the equator. Unchecked—Measure aspect from the North Pole. This is the default. Checked—Measure aspect from a point on the equator.	Boolean

Return Value

Label	Explanation	Data Type
Output raster	The output raster.	Raster

Python

SurfaceParameters(in_raster, {parameter_type}, {local_surface_type}, {neighborhood_distance}, {use_adaptive_neighborhood}, {z_unit}, {output_slope_measurement}, {project_geodesic_azimuths}, {use_equatorial_aspect})

Name	Explanation	Data Type
in_raster	The input surface raster.	Raster Layer
parameter_type (Optional)	Determines the output surface parameter type to compute. SLOPE —The rate of change in elevation. This is the default. ASPECT —The downslope direction of the maximum rate of change for each cell. MEAN_CURVATURE —Measures the overall curvature of the surface. It is computed as the average of the minimum and maximum curvature. This curvature describes the intrinsic convexity or concavity of the surface, independent of direction or gravity influence. TANGENTIAL_CURVATURE —Measures the geometric normal curvature perpendicular to the slope line, tangent to the contour line. This curvature is typically applied to characterize the convergence or divergence of flow across the surface. PROFILE_CURVATURE —Measures the geometric normal curvature along the slope line. This curvature is typically applied to characterize the acceleration and deceleration of flow down the surface.	String
local_surface_type (Optional)	Determines the type of surface function fitted around the target cell. QUADRATIC —Fits a quadratic surface function to the neighborhood cells. This is the default. BIQUADRATIC —Fits a biquadratic surface function to the neighborhood cells.	String
neighborhood_distance (Optional)	The output is calculated over this distance from the target cell center. It determines the neighborhood size. The default value is the input raster cell size, resulting in a 3 x 3 neighborhood.	Linear Unit
use_adaptive_neighborhood (Optional)	Allow neighborhood distance to vary with landscape changes. The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size. FIXED_NEIGHBORHOOD —Use a single (fixed) neighborhood distance at all locations. This is the default. ADAPTIVE_NEIGHBORHOOD —Use an adaptive neighborhood distance at all locations.	Boolean
z_unit (Optional)	The linear unit of vertical z-values. It is defined by a vertical coordinate system if it exists. If a vertical coordinate system does not exist, the z-unit should be defined from 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
output_slope_measurement (Optional)	When parameter_type is SLOPE, determines the measurement units (degrees or percentages) of the output slope raster. DEGREE —The inclination of slope will be calculated in degrees. PERCENT_RISE —The inclination of slope will be calculated as percent rise, also referred to as the percent slope.	String
project_geodesic_azimuths (Optional)	Specifies whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference. GEODESIC_AZIMUTHS —Geodesic azimuths will not be projected. This is the default. PROJECT_GEODESIC_AZIMUTHS —Geodesic azimuths will be projected.	Boolean
use_equatorial_aspect (Optional)	Measure aspect from a point on the equator. NORTH_POLE_ASPECT —Measure aspect from the North Pole. This is the default. EQUATORIAL_ASPECT —Measure aspect from a point on the equator.	Boolean

Return Value

Name	Explanation	Data Type
out_raster	The output raster.	Raster

Code sample

SurfaceParameters example 1 (Python window)

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

This example generates a slope raster with output values in percentages, using an adaptive neighborhood method. The maximum neighborhood distance is 5 meters.

from arcpy.sa import *
outSurfaceParameters = SurfaceParameters("elevation_1m.tif", "", "", "5 METERS",
                                         "ADAPTIVE_NEIGHBORHOOD", "", "PERCENT_RISE")
outSurfaceParameters.save("C:/sapyexamples/output/outsurfaceparameters01.tif")

SurfaceParameters example 2 (stand-alone script)

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

This example generates a profile (normal slope line) curvature raster, using an adaptive neighborhood method. The maximum neighborhood distance is 10 meters.

# Name: SurfaceParameters_Ex_02.py
# Description: Derive profile (normal slope line) curvature for a 1m resolution
# elevation raster over an adaptive neighborhood distance of maximum 10m. 
# 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"
inParameterType = "PROFILE_CURVATURE"
inNeighborhoodDistance = "10 METERS"
inUseAdaptiveNeighborhood = "ADAPTIVE_NEIGHBORHOOD"

# Execute the tool
outSurfaceParameters = SurfaceParameters(inRaster, inParameterType, "",
                                         inNeighborhoodDistance, inUseAdaptiveNeighborhood)

# Save the output 
outSurfaceParameters.save("C:/sapyexamples/output/outsurfaceparameters02.tif")

SurfaceParameters example 3 (stand-alone script)

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

This example generates an aspect raster using a neighborhood distance of 5 meters. Correct for direction distortions from using a non-conformal projection.

# Name: SurfaceParameters_Ex_03.py
# Description: Derive aspect for an elevation surface over a distance of 5m, correct
# for direction distortion from non-conformal projection system. 
# 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"
inParameterType = "ASPECT"
inNeighborhoodDistance = "5 METERS"
inProjectGeodesicAzimuths = "PROJECT_GEODESIC_AZIMUTHS"

# Execute the tool
outSurfaceParameters = SurfaceParameters(inRaster, inParameterType, "",
                                         inNeighborhoodDistance, "", "", "",
                                         inProjectGeodesicAzimuths)

# Save the output 
outSurfaceParameters.save("C:/sapyexamples/output/outsurfaceparameters03.tif")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Scratch Workspace, Snap Raster, Tile Size

Licensing information

• Basic: Requires Spatial Analyst or 3D Analyst
• Standard: Requires Spatial Analyst or 3D Analyst
• Advanced: Requires Spatial Analyst or 3D Analyst