Flow Direction

Flow Direction task

The Flow Direction task creates a raster of flow direction from each cell to its steepest downslope neighbor.

The Flow Direction task supports three flow modeling algorithms. Those are D8, Multi Flow Direction (MFD), and D-Infinity (DINF).

The D8 flow method models flow direction from each cell to its steepest downslope neighbor.

The output of the Flow Direction task run with the D8 flow direction type is an integer raster whose values range from 1 through 255. The values for each direction from the center are the following:

Flow Direction codes

For example, if the direction of steepest drop was to the left of the current processing cell, its flow direction would be coded as 16.

Other flow direction rules are as follows:

  • 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 1 + 4 = 5.
  • If a cell has the same change in z-value in multiple directions and is not part of a sink, the flow direction 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 slope 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 the 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 Force all edge cells to flow outward parameter in the default unchecked setting (NORMAL), a cell at the edge of the surface raster will flow toward the inner cell with the steepest drop in z-value. If the drop is less than or equal to zero, the cell will flow out of the surface raster.

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.

The MFD flow direction output when added to a map only displays the D8 flow directions. 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 Flow Accumulation task that would utilize the MFD flow directions to proportion and accumulate flow from each cell to all downslope neighbors.

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. Flow direction output is a floating-point raster represented as a single angle in degrees going counter-clockwise from 0 (due east) to 360 (again due east).

  • 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.

Request URL

http://<raster analysis url>/FlowDirection/submitJob

Request Parameters

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

ParameterDescription

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, or a cloud raster dataset.

Examples:

  • "inputSufaceRaster": {"itemId": <portal item id>}
  • "inputSufaceRaster": {"url": <image service layer url>}

outputFlowDirectionName

(Required)

The output flow direction image service name that will be created.

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

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.

Output name example:

"outputFlowDirectionName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

"outputFlowDirectionName":{"itemId": <portal item id>}
"outputFlowDirectionName":{"url": <image service url}
"outputFlowDirectionName":{"serviceProperties":
                               {"name":"testrasteranalysis",
                                "serviceUrl":"http://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, 
                                "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}}

forceFlow

Specifies if edge cells will always flow outward or follow normal flow rules.

Syntax: A Boolean value as either true or false.

  • true—Specifies that if the maximum drop on the inside of an edge cell is greater than zero, the flow direction will be determined as usual; otherwise, the flow direction will be toward the edge. Cells that should flow from the edge of the surface raster inward will do so. This is the default.
  • false—Specifies that all cells at the edge of the surface raster will flow outward from the surface raster.

Default: true

flowDirectionType

Specifies the flow direction type to use.

Syntax: A string describing the type, which can be one of the following:

  • D8—Uses the D8 method. This is the default.
  • MFD—Uses the Multi Flow Direction method.
  • DINF—Uses the D-Infinity method.

Example:

  • "dataType": "MFD"

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.

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

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.

Output name example:

"outputDropName":{"serviceProperties":{"name":"testagl"}}

Output raster examples:

"outputDropName":{"itemId": <portal item id>}
"outputDropName":{"url": <image service url}
"outputDropName":{"serviceProperties":
                      {"name":"testagl",
                       "serviceUrl":"http://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, 
                       "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}}

context

Contains additional settings that affect task execution.

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

Response

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

Syntax:

{
"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:

http://<raster analysis url>/FlowDirection/jobs/<jobId>

Accessing results

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:

http://<raster analysis url>/jobs/<jobId>/results/<outputRaster>?token=<your token>&f=json

Replace <outputRaster> with the particular output you are interested in.

ParameterDescription

outputFlowDirectionRaster

This is the output flow direction raster item ID and URL.

Example:

{"url": 
"http://<raster analysis url>/FlowDirection/jobs/<jobId>/results/outputFlowDirectionRaster"}

The result has properties for parameter name, data type, and value. The content of value is always the itemid of the output raster dataset and the image service URL. For example:

{
    "paramName": "outputFlowDirectionRaster",
    "dataType": "GPString",
    "value": {
        "itemId": "f121390b85ef419790479fc75b493efd", 
        "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
    }
}

outputDropRaster

This is the output drop raster item ID and URL.

Example:

{"url": 
"http://<raster analysis url>/FlowDirection/jobs/<jobId>/results/outputDropRaster"}

The result has properties for parameter name, data type, and value. The content of value is always the itemid of the output raster dataset and the image service URL. For example:

{
    "paramName": "outputDropRaster",
    "dataType": "GPString",
    "value": {
        "itemId": "f121390b85ef419790479fc75b493efd", 
        "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
    } 
}