Surface Parameters (Raster Analysis)

Summary

Determines parameters of a surface raster such as aspect, slope, and several types of curvatures using geodesic methods.

Calculations are performed on a cell-by-cell basis by fitting a local surface around a target cell.

Usage

  • This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise portal that has an ArcGIS Image Server configured for Raster Analysis. When the tool is invoked, ArcGIS Pro serves as a client and the processing occurs in the servers federated with ArcGIS Enterprise. The portal tool accepts layers from your portal as input and creates output in your portal.

    The input raster layer supports a layer from the portal, a URI or URL to an image service, or the output from the Make Image Server Layer tool. The input feature layer can be a layer from the portal or a URI or URL to a feature service. This tool does not support local raster data or layers. While you can use local feature data and layers as input to this portal tool, best practice is to use layers from your portal as input.

  • When the Slope 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 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 explain 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. The curvature options for Parameter Type are described as follows:

    • Mean curvature—The overall curvature of the surface. It is computed as the average of the minimum and maximum curvature. When this option is specified, 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).
    • Tangential (normal contour) curvature—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.
    • Profile (normal slope line) curvature—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.
    • Plan (projected contour) curvature—The curvature along contour lines.
    • Contour geodesic torsion—The rate of change in slope angle along contour lines.
    • Gaussian curvature—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—The general curvature of the surface. It can be zero or always 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 setting.

  • The Quadratic option of the Local Surface Type parameter 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 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 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.
  • When the Use Adaptive Neighborhood parameter is checked (useAdaptiveNeighborhood = "ADAPTIVE_NEIGHBORHOOD" in Python), the neighborhood distance will change with variability in the terrain. The neighborhood distance will lessen if there is too much variability in the calculation window.

  • Specifying the surface Z Unit 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 Output Slope Measurement parameter value:

    • Degrees—The range of slope values is 0 to 90.
    • Percent rise—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 (projectGeodesicAzimuths = "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 environment system value. These angles can be used to accurately locate points along the steepest downhill slope.

  • If the Use Equatorial Aspect parameter is checked (useEquatorialAspect = "EQUATORIAL_ASPECT" in Python), aspect will be measured from a point along the equator to correct 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 the north or south pole.

Parameters

LabelExplanationData Type
Input Surface Raster

The input surface raster. It can be integer or floating point type.

Raster Layer; Image Service; String
Output Raster Name

The name of the output raster service.

String
Parameter Type
(Optional)

Specifies the output surface parameter type that will be computed.

  • SlopeThe rate of change in elevation will be computed. This is the default.
  • AspectThe downslope direction of the maximum rate of change for each cell will be computed.
  • Mean curvatureThe overall curvature of the surface will be measured. 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) curvatureThe geometric normal curvature perpendicular to the slope line, tangent to the contour line will be measured. This curvature is typically applied to characterize the convergence or divergence of flow across the surface.
  • Profile (normal slope line) curvatureThe geometric normal curvature along the slope line will be measured. This curvature is typically applied to characterize the acceleration and deceleration of flow down the surface.
  • Plan (projected contour) curvatureThe curvature along contour lines will be measured.
  • Contour geodesic torsionThe rate of change in slope angle along contour lines will be measured.
  • Gaussian curvatureThe overall curvature of the surface will be measured. It is computed as the product of the minimum and maximum curvature.
  • Casorati curvatureThe general curvature of the surface will be measured. It can be zero or any other positive number.
String
Local Surface Type
(Optional)

Specifies the type of surface function that will be fitted around the target cell.

  • QuadraticA quadratic surface function will be fitted to the neighborhood cells. This is the default.
  • BiquadraticA biquadratic surface function will be fitted to the neighborhood cells.
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.

  • Unchecked—A single (fixed) neighborhood distance will be used at all locations. This is the default.
  • Checked—An adaptive neighborhood distance will be used 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.

  • InchThe linear unit will be inches.
  • FootThe linear unit will be feet.
  • YardThe linear unit will be yards.
  • Mile USThe linear unit will be miles.
  • Nautical mileThe linear unit will be nautical miles.
  • MillimeterThe linear unit will be millimeters.
  • CentimeterThe linear unit will be centimeters.
  • MeterThe linear unit will be meters.
  • KilometerThe linear unit will be kilometers.
  • DecimeterThe linear unit will be decimeters.
String
Output Slope Measurement
(Optional)

The measurement units (degrees or percentages) that will be used for the output slope raster. This parameter is only active when Parameter Type is Slope.

  • DegreeThe inclination of slope will be calculated in degrees.
  • Percent riseThe 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)

Specifies whether aspect will be measured from a point on the equator or from the north pole.

  • Unchecked—Aspect will be measured from the north pole. This is the default.
  • Checked—Aspect will be measured from a point on the equator.
Boolean

Derived Output

LabelExplanationData Type
Output Raster

The output surface parameter raster.

Raster Layer

arcpy.ra.SurfaceParameters(inputSurfaceRaster, outputRasterName, {parameterType}, {localSurfaceType}, {neighborhoodDistance}, {useAdaptiveNeighborhood}, {zUnit}, {outputSlopeMeasurement}, {projectGeodesicAzimuths}, {useEquatorialAspect})
NameExplanationData Type
inputSurfaceRaster

The input surface raster. It can be integer or floating point type.

Raster Layer; Image Service; String
outputRasterName

The name of the output raster service.

String
parameterType
(Optional)

Specifies the output surface parameter type that will be computed.

  • SLOPEThe rate of change in elevation will be computed. This is the default.
  • ASPECTThe downslope direction of the maximum rate of change for each cell will be computed.
  • MEAN_CURVATUREThe overall curvature of the surface will be measured. 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_CURVATUREThe geometric normal curvature perpendicular to the slope line, tangent to the contour line will be measured. This curvature is typically applied to characterize the convergence or divergence of flow across the surface.
  • PROFILE_CURVATUREThe geometric normal curvature along the slope line will be measured. This curvature is typically applied to characterize the acceleration and deceleration of flow down the surface.
  • CONTOUR_CURVATUREThe curvature along contour lines will be measured.
  • CONTOUR_GEODESIC_TORSIONThe rate of change in slope angle along contour lines will be measured.
  • GAUSSIAN_CURVATUREThe overall curvature of the surface will be measured. It is computed as the product of the minimum and maximum curvature.
  • CASORATI_CURVATUREThe general curvature of the surface will be measured. It can be zero or any other positive number.
String
localSurfaceType
(Optional)

Specifies the type of surface function that will be fitted around the target cell.

  • QUADRATICA quadratic surface function will be fitted to the neighborhood cells. This is the default.
  • BIQUADRATICA biquadratic surface function will be fitted to the neighborhood cells.
String
neighborhoodDistance
(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
useAdaptiveNeighborhood
(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.

  • FIXED_NEIGHBORHOODA single (fixed) neighborhood distance will be used at all locations. This is the default.
  • ADAPTIVE_NEIGHBORHOODAn adaptive neighborhood distance will be used at all locations.
Boolean
zUnit
(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.

  • INCHThe linear unit will be inches.
  • FOOTThe linear unit will be feet.
  • YARDThe linear unit will be yards.
  • MILE_USThe linear unit will be miles.
  • NAUTICAL_MILEThe linear unit will be nautical miles.
  • MILLIMETERThe linear unit will be millimeters.
  • CENTIMETERThe linear unit will be centimeters.
  • METERThe linear unit will be meters.
  • KILOMETERThe linear unit will be kilometers.
  • DECIMETERThe linear unit will be decimeters.
String
outputSlopeMeasurement
(Optional)

The measurement units (degrees or percentages) that will be used for the output slope raster. This parameter is only enabled when parameterType = "SLOPE".

  • DEGREEThe inclination of slope will be calculated in degrees.
  • PERCENT_RISEThe inclination of slope will be calculated as percent rise, also referred to as the percent slope.
String
projectGeodesicAzimuths
(Optional)

Specifies whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference.

  • GEODESIC_AZIMUTHSGeodesic azimuths will not be projected. This is the default.
  • PROJECT_GEODESIC_AZIMUTHSGeodesic azimuths will be projected.
Boolean
useEquatorialAspect
(Optional)

Specifies whether aspect will be measured from a point on the equator or from the north pole.

  • NORTH_POLE_ASPECTAspect will be measured from the north pole. This is the default.
  • EQUATORIAL_ASPECTAspect will be measured from a point on the equator.
Boolean

Derived Output

NameExplanationData Type
outputRaster

The output surface parameter raster.

Raster Layer

Code sample

SurfaceParameters example 1 (Python window)

This example calculates slope in degrees using a fixed 3 by 3 neighborhood window and the output is saved as an image service layer, given an input surface.

import arcpy

arcpy.SurfaceParameters_ra(
    "https://myserver/rest/services/elevation/ImageServer", 
    "out_surfaceparameters", "SLOPE", "QUADRATIC", 
    "", "FIXED_NEIGHBORHOOD", "", "DEGREE", "", "")
SurfaceParameters example 2 (stand-alone script)

This example creates a tangential curvature image service using an adaptive neighborhood window, given an input surface.

#---------------------------------------------------------------------------
# Name: SurfaceParameters_standalone.py
# Description: Calculates tangential curvature using 
#              an adaptive neighborhood from an input surface. 
#
# Requirements: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables

inputSurface = "https://myserver/rest/services/elevation/ImageServer"
outName = "outsurfp1"
parameterType = "TANGENTIAL_CURVATURE"
localSurfaceType = "QUADRATIC"
neighborhoodDistance = "2 Meters"
useAdaptiveNeighborhood = "ADAPTIVE_NEIGHBORHOOD"
zUnit = "#"
outputSlopeMeasure = "#"
projectGeodesicAzimuth = "#"
useEquatorialAspect = "#"

# Execute Surface Parameters raster analysis tool

arcpy.SurfaceParameters_ra(inputSurface, 
                           outName, 
                           parameterType,
                           localSurfaceType, 
                           neighborhoodDistance,
                           useAdaptiveNeighborhood, 
                           zUnit,
                           outputSlopeMeasure,
                           projectGeodesicAzimuth,
                           useEquatorialAspect)

Licensing information

  • Basic: Requires ArcGIS Image Server
  • Standard: Requires ArcGIS Image Server
  • Advanced: Requires ArcGIS Image Server

Related topics