- URL:https://<rasteranalysistools-url>/FlowDirection
- Version Introduced:10.6
Description
The FlowDirection task creates a raster of flow direction from each cell to its steepest downslope neighbor.
This task supports three flow modeling algorithms. Those are D8, Multi Flow Direction (MFD), and D-Infinity (DINF).
D8 flow modeling algorithm
The D8 flow method models flow direction from each cell to its steepest downslope neighbor.
The output of the FlowDirection task run with the D8 flow direction type is an integer raster whose values range from 1-255. The values for each direction from the center are the following:
For example, if the direction of steepest drop was to the left of the current processing cell, its flow direction would be coded at 16.
The following are additional considerations for using the D8 flow method:
- If a cell is lower than its eight neighbors, that cell is given the value of its lowest neighbor, and flow is defined toward this cell. If multiple neighbors have the lowest value, the cell is still given this value, but flow is defined with one of the two methods explained below. This is used to filter out one-cell sinks, which are considered noise.
- If a cell has the same change in z-value in multiple directions and that cell is part of a sink, the flow direction is referred to as undefined. In such cases, the value for that cell in the output flow direction raster will be the sum of those directions. For example, if the change in z-value is the same both to the right (flow direction = 1) and down (flow direction = 4), the flow direction for that cell is 5.
- If a cell has the same change in z-value in multiple directions and is not part of a sink, the flow directions is assigned with a lookup table defining the most likely direction. See Greenlee (1987).
- The output drop raster is calculated as the difference in z-value divided by the path length between the cell centers, expressed in percentages. For adjacent cells, this is analogous to the percent slop between cells. Across a flat area, the distance becomes the distance to the nearest cell of lower elevation. The result is a map of percent rise in the path of steepest descent from each cell.
- When calculating a drop raster in flat areas, the distance to diagonally adjacent cells (1.41421 * cell size) is approximated by 1.5 * cell size for improved performance.
- With the forceFlow parameter set to the default value False, a cell at the edge of the surface raster will flow towards the inner cell with the steepest z-value. If the drop is less than or equal to zero, the cell will flow out of the surface raster.
MFD flow modeling algorithm
The MFD algorithm, described by Qin et al. (2007), partitions flow from a cell to all downslope neighbors. A flow-partition exponent is created from an adaptive approach based on local terrain conditions and is used to determine fraction of flow draining to all downslope neighbors.
When the MFD flow direction output is added to a map, it only displays the D8 flow direction. As MFD flow directions have potentially multiple values tied to each cell (each value corresponds to proportion of flow to each downslope neighbor), it is not easily visualized. However, an MFD flow direction output raster is an input recognized by the FlowAccumulation task that would utilize the MFD flow directions to proportion and accumulate flow from each cell to all downslope neighbors.
DINF flow modeling algorithm
The DINF flow method, described by Tarboton (1997), determines flow direction as the steepest downward slope on eight triangular facets formed in a 3x3 cell window centered on the cell of interest. The flow direction output is a floating-point raster represented as a single angle in degrees going counter-clockwise from 0 (due east) to 360 (also due east).
Request parameters
| Parameter | Details |
|---|---|
| inputSurfaceRaster (Required) | The input raster representing a continuous surface. 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: |
| outputFlowDirectionName (Required) | The output flow direction image service name 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: Output raster examples: |
| forceFlow | Specifies if edge cells will always flow outward or follow normal flow rules. Syntax: A Boolean value as either true or false.
|
| flowDirectionType | Specifies the flow direction type to use. Syntax: A string describing the flow direction type, which can be one of the following:
|
| outputDropName | The optional output name drop image service name. The drop raster returns the ratio of the maximum change in elevation from each cell along the direction of flow to the path length between centers of cells, expressed in percentages. 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 drop raster. Output name example: Output raster examples: |
| context | Contains additional settings that affect task processing. This task has the following settings:
|
| 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.
{
"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:
https://<raster analysis tools url>/FlowDirection/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:
https://<raster analysis tools url>/FlowDirection/jobs/<jobId>/results/<output parameter>
Example usage
Below is a sample request URL for FlowDirection.
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/FlowDirection/submitJob
JSON Response example
The response returns the outputFlowDirectionRaster and outputDropRaster output parameters, which have properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.
{
"paramName": "outputFlowDirectionRaster",
"dataType": "GPString",
"value": {
"itemId": "f121390b85ef419790479fc75b493efd",
"url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
}
}References
Greenlee, D. D. 1987. "Raster and Vector Processing for Scanned Linework." Photogrammetric Engineering and Remote Sensing 53(10): 1383-1387.
Tarboton, D. G. 1997. "A new method for the determination of flow directions and upslope areas in grid digital elevation models." Water Resources Research 33(2): 309-319.
Qin, C., Zhu, A. X., Pei, T., Li, B., Zhou, C., & Yang, L. 2007. "An adaptive approach to selecting a flow partition exponent for a multiple flow direction algorithm." International Journal of Geographical Information Science 21(4): 443-458.