| Label | Explanation | Data Type |
Input surface raster | The input surface raster. | Raster Layer |
Output raster | The output raster. It will be floating-point type. | Raster Dataset |
Parameter type (Optional) | Specifies the output surface parameter type that will be computed.
| String |
Local surface type (Optional) | Specifies the type of surface function that will be fitted around the target cell.
| String |
Neighborhood distance (Optional) | The output will be 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 by 3 neighborhood. | Linear Unit |
Use adaptive neighborhood (Optional) | Specifies whether neighborhood distance will vary with landscape changes (adaptive). The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size.
| Boolean |
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 no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter.
| String |
Slope measurement (Optional) | The measurement units (degrees or percentages) that will be used for the output slope raster. This parameter is only available if the Parameter type parameter is set to Slope.
| String |
Project geodesic azimuths (Optional) |
Specifies whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference.
This parameter is only available if the Parameter type parameter is set to Aspect. | Boolean |
Use equatorial aspect (Optional) |
Specifies whether aspect will be measured from a point on the equator or from the north pole.
This parameter is only available if the Parameter type parameter is set to Aspect. | Boolean |
Input analysis mask (Optional) | The input data defining the locations where the analysis will occur. It can be a raster or feature dataset. If the input is a raster, it can be integer or floating-point type. If the input is feature data, it can be point, line, or polygon type. When the input mask data is a raster, the analysis will occur at locations that have a valid value, including zero. Cells that are NoData in the mask input will be NoData in the output. | Composite Geodataset |
Summary
Determines parameters of a raster surface such as aspect, slope, and curvatures.
Usage
The output parameters are calculated on a cell-by-cell basis by fitting a local surface around a target cell. The available surface parameter options for the Parameter type parameter (parameter_type in Python) are Slope, Aspect, Mean curvature, Tangential (normal contour) curvature, Profile (normal slope line) curvature, Plan (projected contour) curvature, Contour geodesic torsion, Gaussian curvature, and Casorati curvature.
All output parameters are calculated using geodesic coordinates and equations.
When the Slope (SLOPE in Python) option is specified for 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 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 factors on the surface and is used in conjunction with other surface parameters to identify and classify landforms.
- Mean curvature (MEAN_CURVATURE in Python)—The overall curvature of the surface. It is computed as the average of the minimum and maximum curvature. When this is specified for Parameter type, the output is equivalent to the 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).
- Profile (normal slope line) curvature (PROFILE_CURVATURE in Python)—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 that the surface is convex at that cell in the direction of the slope. A negative curvature indicates that the surface is concave at that cell in that same direction. A value of 0 indicates that the surface is flat.
- Tangential (normal contour) curvature (TANGENTIAL_CURVATURE in Python)—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 that the surface is convex at that cell perpendicular to the direction of the slope. A negative curvature indicates that the surface is concave at that cell in the direction perpendicular to the slope. A value of 0 indicates that the surface is flat.
- Plan (projected contour) curvature (CONTOUR_CURVATURE in Python)—The curvature along contour lines.
- Contour geodesic torsion (CONTOUR_GEODESIC_TORSION in Python)—The rate of change in slope angle along contour lines.
- Gaussian curvature (GAUSSIAN_CURVATURE in Python)—The general curvature of a surface. It is computed as the product of the minimum and maximum curvature and can take negative and positive values. Positive values indicate that the surface is convex at that cell, while negative values indicate that it is concave. A value of 0 indicates that the surface is flat.
- Casorati curvature (CASORATI_CURVATURE in Python)—The general curvature of the surface. It can be zero or positive. High positive values indicate areas of sharp bending in multiple directions.
The units of all curvature type outputs will be the reciprocal (the square of the reciprocal for Gaussian curvature) of the x,y-units of the Output Coordinate System environment.
The Quadratic option of the Local surface type parameter (local_surface_type = "QUADRATIC" 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.
- Use the quadratic surface when specifying a neighborhood size that is larger than the cell size and when using the adaptive neighborhood option.
The Biquadratic option of the Local surface type parameter (local_surface_type = "BIQUADRATIC" in Python) 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. Leave the neighborhood distance as the default (equal to the cell size).
The Neighborhood distance (neighborhood_distance in Python) parameter 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, such as 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 = "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) parameter value ensures 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 recommended 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 Slope measurement (output_slope_measurement in Python) parameter measurement units:
- Degree (DEGREE in Python)—The range of slope values is 0 to 90.
- 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 = "PROJECT_GEODESIC_AZIMUTHS" in Python), the following are true:
- North is represented by 360 degrees.
- Azimuths will be projected to correct the distortion caused by a nonconformal Output Coordinate System environment value. These angles can be used to accurately locate points along the steepest downhill slope.
If the Use equatorial aspect parameter is checked (project_geodesic_azimuths = "USE_EQUATORIAL_ASPECT" in Python), aspect will be measured from a point along the equator to correct for the skewing of direction that occurs when approaching the poles. This parameter ensures that the north-south and east-west axes are perpendicular to each other.
Check the Use equatorial aspect parameter if the terrain is near to the north or south pole.
Use the Input analysis mask parameter (in_analysis_mask in Python) to limit the analysis to specific locations of interest within the input surface raster. The locations can be defined by raster or feature data. The Input analysis mask parameter will take priority over the Mask environment setting.
When the Input surface raster (in_raster in Python) value and the Input analysis mask raster data (in_analysis_mask in Python) are of the same cell size and the cells are aligned, they will be used directly in the tool. They will not be resampled internally during tool operation.
If the cell size is different, the output cell size will be the maximum of the inputs, and the Input surface raster value will be used internally as the snap raster. If the cell size is the same but the cells are not aligned, the Input surface raster value will be used internally as the snap raster. Either of these cases will trigger an internal resampling before the extraction operation is performed.
For additional information, see the Cell Size and Snap Raster environment topics.
References:
James, D. E., Tomer, M. D., and Porter, S. A. 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., and Jenčo, M. A comprehensive system of definitions of land surface (topographic) curvatures, with implications for their application in geoscience modelling and prediction. Earth-Science Reviews, 103414, 2020. https://doi.org/10.1016/j.earscirev.2020.103414
Parameters
arcpy.ddd.SurfaceParameters(in_raster, out_raster, {parameter_type}, {local_surface_type}, {neighborhood_distance}, {use_adaptive_neighborhood}, {z_unit}, {output_slope_measurement}, {project_geodesic_azimuths}, {use_equatorial_aspect}, {in_analysis_mask})| Name | Explanation | Data Type |
in_raster | The input surface raster. | Raster Layer |
out_raster | The output raster. It will be floating-point type. | Raster Dataset |
parameter_type (Optional) | Specifies the output surface parameter type that will be computed.
| String |
local_surface_type (Optional) | Specifies the type of surface function that will be fitted around the target cell.
| String |
neighborhood_distance (Optional) | The output will be 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 by 3 neighborhood. | Linear Unit |
use_adaptive_neighborhood (Optional) | Specifies whether neighborhood distance will vary with landscape changes (adaptive). The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size.
| Boolean |
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 no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter.
| String |
output_slope_measurement (Optional) | The measurement units (degrees or percentages) that will be used for the output slope raster.
This parameter is only supported if the parameter_type parameter is set to SLOPE. | String |
project_geodesic_azimuths (Optional) |
Specifies whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference.
This parameter is only supported if the parameter_type parameter is set to ASPECT. | Boolean |
use_equatorial_aspect (Optional) |
Specifies whether aspect will be measured from a point on the equator or from the north pole.
This parameter is only supported if the parameter_type parameter is set to ASPECT. | Boolean |
in_analysis_mask (Optional) | The input data defining the locations where the analysis will occur. It can be a raster or feature dataset. If the input is a raster, it can be integer or floating-point type. If the input is feature data, it can be point, line, or polygon type. When the input mask data is a raster, the analysis will occur at locations that have a valid value, including zero. Cells that are NoData in the mask input will be NoData in the output. | Composite Geodataset |
Code sample
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.ddd import *
SurfaceParameters("elevation_1m.tif", "C:/data/output/outsurfaceparameters01.tif",
"", "", "5 METERS", "ADAPTIVE_NEIGHBORHOOD", "", "PERCENT_RISE")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: 3D Analyst Extension
# Import system modules
import arcpy
from arcpy.ddd import *
# Set environment settings
arcpy.env.workspace = "C:/data"
# Check out the ArcGIS 3D Analyst extension license
arcpy.CheckOutExtension("3D")
# Set local variables
inRaster = "elevation_1m.tif"
outRaster = "C:/data/output/outsurfaceparameters02.tif"
inParameterType = "PROFILE_CURVATURE"
inNeighborhoodDistance = "10 METERS"
inUseAdaptiveNeighborhood = "ADAPTIVE_NEIGHBORHOOD"
# Execute the tool
SurfaceParameters(inRaster, outRaster, inParameterType, "",
inNeighborhoodDistance, inUseAdaptiveNeighborhood)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 nonconformal 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: 3D Analyst Extension
# Import system modules
import arcpy
from arcpy.ddd import *
# Set environment settings
arcpy.env.workspace = "C:/data"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("3D")
# Set local variables
inRaster = "elevation_1m.tif"
outRaster = "C:/data/output/outsurfaceparameters03.tif"
inParameterType = "ASPECT"
inNeighborhoodDistance = "5 METERS"
inProjectGeodesicAzimuths = "PROJECT_GEODESIC_AZIMUTHS"
# Execute the tool
SurfaceParameters(inRaster, outRaster, inParameterType, "", inNeighborhoodDistance,
"", "", "", inProjectGeodesicAzimuths)