Surface Parameters

URL:: https://<root>/<serviceName>/RasterAnalysisTools/GPServer/SurfaceParameters
Methods:: GET
Version Introduced:: 11.0

Description

The SurfaceParameters task determines parameters of a surface raster such as various types of curvatures, slope, and aspect.

Example applications of SurfaceParameters include the following:

Calculate different types of curvatures. An example is TANGENTIAL_CURVATURE, which characterizes topographic convergence and divergence of flow across the surface.
Calculate aspect and slope using geodesic methods.

Request parameters

The following table lists the parameters with syntax and details for each:

Parameter Details

Parameter	Details
`inputSurfaceRaster` (Required)	The input surface raster. Syntax: This parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. Examples: Use dark colors for code blocksCopy `1 2 3 4 5 //Input surface raster as portal item "inputSurfaceRaster": {"itemId": <portal item id>} //Input surface raster as URL "inputSurfaceRaster": {"url": <image service layer url>}`
`outputName` (Required)	The name of the output image service that will be created. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: Use dark colors for code blocksCopy `1 "outputName":{"serviceProperties":{"name":"testrasteranalysis"}}` Output raster examples: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 //Output portal item: "outputName":{"itemId": <portal item id>} //Output url: "outputName":{"url": <image service url} //Output raster layer service: "outputName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }`
`parameterType`	Specify the surface parameter type that will be computed. Syntax: The input can be one of the following: `SLOPE` —The rate of change in elevation will be computed. This is the default. `ASPECT` —The downslope direction of the maximum rate of change for each cell will be computed. `MEAN_CURVATURE` —The 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_CURVATURE` —The geometric normal curvature perpendicular to the slope line and 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_CURVATURE` —The 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_CURVATURE` —The curvature along contour lines will be measured. `CONTOUR_GEODESIC_TORSION` —The rate of change in slope angle along contour lines will be measured. `GAUSSIAN_CURVATURE` —The overall curvature of the surface will be measured. It is computed as the product of the minimum and maximum curvature. `CASORATI_CURVATURE` —The general curvature of the surface will be measured. It can be zero or any other positive number. Example: Use dark colors for code blocksCopy `1 "parameterType": "ASPECT"`
`localSurfaceType`	Specify the type of surface function that will be fitted around the target cell. Syntax: A string describing the local surface type to be fitted. The following are the available local surface types: `QUADRATIC` —A quadratic surface function will be fitted to the neighborhood cells. This is the default. `BIQUADRATIC` —A biquadratic surface function will be fitted to the neighborhood cells Example: Use dark colors for code blocksCopy `1 "localSurfaceType": "BIQUADRATIC"`
`neighborhoodDistance`	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. Syntax: A linear unit specifying the distance and units. Supported units: `Kilometers` \| `Meters` \| `Decimeters` \| `Centimeters` \| `Millimeters` \| `Nautical Miles` \| `Miles` \| `Yards` \| `Feet` \| `Inches` \| `Decimal Degrees` \| `Points` Example: Use dark colors for code blocksCopy `1 "neighborhoodDistance": {"distance": <value>, "units": <unit>}`
`useAdaptiveNeighborhood`	Specify whether the `neighborhoodDistance` value will vary with landscape changes (adaptive). The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size. Syntax: A Boolean value as either `true` or `false` . If `true` , an adaptive neighborhood distance will be used at all locations. If `false` , a single (fixed) neighborhood distance will be used at all locations. This is the default.
`zUnit`	Specify 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, it is recommended that you define the z-unit from the unit list to ensure correct geodesic computation. The default is meter. Syntax: A string specifying the 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. Example: Use dark colors for code blocksCopy `1 "zUnit": "KILOMETER"`
`outputSlopeMeasurement`	Specify the measurement units that will be used for the output slope raster. This parameter is only applicable when the `parameterType` value is `SLOPE` . Syntax: A string specifying the slope measurement units. `DEGREE` —The inclination of slope will be calculated in degrees. This is the default. `PERCENT_RISE` —The inclination of slope will be calculated as percent rise, also referred to as the percent slope. Example: Use dark colors for code blocksCopy `1 "outputSlopeMeasurement": "DEGREE"`
`projectGeodesicAzimuths`	Specify whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference. This parameter is only applicable when the `parameterType` value is `ASPECT` . Syntax: A Boolean value as either `false` or `true` . If `false` , geodesic azimuths will not be projected. This is the default. If `true` , geodesic azimuths will be projected.
`useEquatorialAspect`	Specify whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference. This parameter is only applicable when the `parameterType` value is `ASPECT` . Syntax: A Boolean value as either `false` or `true` . If `false` , geodesic azimuths will not be projected. This is the default. If `true` , geodesic azimuths will be projected.
`inputAnalysisMask`	The input data defining the locations where the analysis will occur. It can be a raster or feature. 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.
`context`	Contains additional settings that affect task processing. This task has the following settings: Extent (`extent` )—A bounding box that defines the analysis area. Output Spatial Reference (`outSR` )—The output raster will be projected into the output spatial reference. Snap Raster (`snapRaster` )—The output raster will have its cells aligned with the specified snap raster. Cell Size (`cellSize` )—The output raster will have the resolution specified by cell size. Mask (`mask`)—Only cells that fall within the analysis mask will be considered in the operation.
`f`	The response format. The default response format is `html` . Values: `html \| json \| pjson`

inputSurfaceRaster

(Required)

The input surface raster.

Syntax: This parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset.

Examples:

Use dark colors for code blocksCopy
//Input surface raster as portal item
"inputSurfaceRaster": {"itemId": <portal item id>}

//Input surface raster as URL
"inputSurfaceRaster": {"url": <image service layer url>}

outputName

(Required)

The name of the output image service that will be created.

You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter.

Syntax: A JSON object describes the name of the output or the output raster.

Output name example:

Use dark colors for code blocksCopy
"outputName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

Use dark colors for code blocksCopy
//Output portal item:
"outputName":{"itemId": <portal item id>}

//Output url:
"outputName":{"url": <image service url}

//Output raster layer service:
"outputName":{"serviceProperties":
  {"name":"testrasteranalysis",
    "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"},
  "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}
}

parameterType

Specify the surface parameter type that will be computed.

Syntax: The input can be one of the following:

SLOPE —The rate of change in elevation will be computed. This is the default.
ASPECT —The downslope direction of the maximum rate of change for each cell will be computed.
MEAN_CURVATURE —The 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_CURVATURE —The geometric normal curvature perpendicular to the slope line and 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_CURVATURE —The 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_CURVATURE —The curvature along contour lines will be measured.
CONTOUR_GEODESIC_TORSION —The rate of change in slope angle along contour lines will be measured.
GAUSSIAN_CURVATURE —The overall curvature of the surface will be measured. It is computed as the product of the minimum and maximum curvature.
CASORATI_CURVATURE —The general curvature of the surface will be measured. It can be zero or any other positive number.

Example:

Use dark colors for code blocksCopy
"parameterType": "ASPECT"

localSurfaceType

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

Syntax: A string describing the local surface type to be fitted. The following are the available local surface types:

QUADRATIC —A quadratic surface function will be fitted to the neighborhood cells. This is the default.
BIQUADRATIC —A biquadratic surface function will be fitted to the neighborhood cells

Example:

Use dark colors for code blocksCopy
"localSurfaceType": "BIQUADRATIC"

neighborhoodDistance

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.

Syntax: A linear unit specifying the distance and units.

Example:

Use dark colors for code blocksCopy
"neighborhoodDistance": {"distance": <value>, "units": <unit>}

useAdaptiveNeighborhood

Specify whether the neighborhoodDistance value will vary with landscape changes (adaptive). The maximum distance is determined by the neighborhood distance. The minimum distance is the input raster cell size.

Syntax: A Boolean value as either true or false .

If true , an adaptive neighborhood distance will be used at all locations.
If false , a single (fixed) neighborhood distance will be used at all locations. This is the default.

zUnit

Specify 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, it is recommended that you define the z-unit from the unit list to ensure correct geodesic computation. The default is meter.

Syntax: A string specifying the 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.

Example:

Use dark colors for code blocksCopy
"zUnit": "KILOMETER"

outputSlopeMeasurement

Specify the measurement units that will be used for the output slope raster. This parameter is only applicable when the parameterType value is SLOPE .

Syntax: A string specifying the slope measurement units.

DEGREE —The inclination of slope will be calculated in degrees. This is the default.
PERCENT_RISE —The inclination of slope will be calculated as percent rise, also referred to as the percent slope.

Example:

Use dark colors for code blocksCopy
"outputSlopeMeasurement": "DEGREE"

projectGeodesicAzimuths

Specify whether geodesic azimuths will be projected to correct the angle distortion caused by the output spatial reference. This parameter is only applicable when the parameterType value is ASPECT .

Syntax: A Boolean value as either false or true .

If false , geodesic azimuths will not be projected. This is the default.
If true , geodesic azimuths will be projected.

useEquatorialAspect

Syntax: A Boolean value as either false or true .

If false , geodesic azimuths will not be projected. This is the default.
If true , geodesic azimuths will be projected.

inputAnalysisMask

The input data defining the locations where the analysis will occur.

It can be a raster or feature. 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.

context

Contains additional settings that affect task processing. This task has the following settings:

Extent (extent )—A bounding box that defines the analysis area.
Output Spatial Reference (outSR )—The output raster will be projected into the output spatial reference.
Snap Raster (snapRaster )—The output raster will have its cells aligned with the specified snap raster.
Cell Size (cellSize )—The output raster will have the resolution specified by cell size.
Mask (mask)—Only cells that fall within the analysis mask will be considered in the operation.

f

The response format. The default response format is html .

Values: html | json | pjson

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Use dark colors for code blocksCopy
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/SurfaceParameters/jobs/<jobId>

When the status of the job request is esriJobSucceeded , you can access the results of the analysis by making a request of the following form:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/SurfaceParameters/jobs/<jobId>/results/<output parameters>

Example usage

The following is a sample request URL for SurfaceParameters :

Use dark colors for code blocksCopy
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/SurfaceParameters/submitJob

JSON Response syntax

The response returns the outputRaster output parameter, which has properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.

Use dark colors for code blocksCopy
{
  "paramName": <parameter name>,
  "dataType": "GPString",
  "value": {
    "itemId": <item Id>,
    "url": <URL>
  }
}

JSON Response example

Use dark colors for code blocksCopy
{
  "paramName": "outRaster",
  "dataType": "GPString",
  "value": {
    "itemId": "f121390b85ef419790479fc75b493efd",
    "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
  }
}