Watershed (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Determines the contributing area above a set of cells in a raster.

Learn more about how Watershed works

Illustration

Usage

• The value of each watershed will be taken from the value of the source in the input raster or feature pour point data. When the pour point is a raster dataset, the cell values will be used. When the pour point is a point feature dataset, the values will come from the specified field.

• The Watershed tool only supports a D8-type of input flow direction raster. This can be created using the Flow Direction tool, run with default flow direction type D8 (in Python, with the D8 option).

• Better results will be obtained if the Snap Pour Point tool is used beforehand to help locate the pour points to cells of high accumulated flow.

• When specifying the input pour point locations as feature data, the default field will be the first available valid field. If no valid field exists, the ObjectID field (for example, OID or FID) will be the default.

• This tool supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. The Parallel processing with Spatial Analyst help topic includes details about this capability and how to configure it.

  When using parallel processing, temporary data will be written to manage the data chunks being processed. The default temp folder location will be on your local C: drive. You can control the location of this folder by setting up a system environment variable named TempFolders and specifying the path to a folder to use (for example, E:\RasterCache). If you have administrator privileges on your machine, you can also use a registry key (for example, [HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Raster]).

  By default, this tool will use 50 percent of the available cores. If the input data is smaller than 5,000 by 5,000 cells in size, fewer cores may be used. You can control the number of cores the tool uses with the Parallel processing factor environment.

• When the output raster format is .crf, this tool supports the Pyramid raster storage environment. Pyramids will be created in the output by default. For any other output format, this environment is not supported, and pyramids will not be created.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input D8 flow direction raster	The input raster that shows the direction of flow out of each cell. The flow direction raster can be created using the Flow Direction tool, run using the default flow direction type D8.	Raster Layer
Input raster or feature pour point data	The input pour point locations. For a raster, this represents cells above which the contributing area, or catchment, will be determined. All cells that are not NoData will be used as source cells. For a point feature dataset, this represents locations above which the contributing area, or catchment, will be determined.	Raster Layer; Feature Layer
Pour point field (Optional)	The field used to assign values to the pour point locations. If the pour point dataset is a raster, use Value. If the pour point dataset is a feature, use a numeric field. If the field contains floating-point values, they will be truncated into integers.	Field

Return Value

Label	Explanation	Data Type
Output raster	The output raster that shows the contributing area. This output is of integer type.	Raster

Python

Watershed(in_flow_direction_raster, in_pour_point_data, {pour_point_field})

Name	Explanation	Data Type
in_flow_direction_raster	The input raster that shows the direction of flow out of each cell. The flow direction raster can be created using the Flow Direction tool, run using the default flow direction type D8.	Raster Layer
in_pour_point_data	The input pour point locations. For a raster, this represents cells above which the contributing area, or catchment, will be determined. All cells that are not NoData will be used as source cells. For a point feature dataset, this represents locations above which the contributing area, or catchment, will be determined.	Raster Layer; Feature Layer
pour_point_field (Optional)	The field used to assign values to the pour point locations. If the pour point dataset is a raster, use Value. If the pour point dataset is a feature, use a numeric field. If the field contains floating-point values, they will be truncated into integers.	Field

Return Value

Name	Explanation	Data Type
out_raster	The output raster that shows the contributing area. This output is of integer type.	Raster

Code sample

Watershed example 1 (Python window)

This example determines the contributing area for selected pour point locations on a flow direction Grid raster.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outWatershed = Watershed("flowdir", "pourpoint")
outWatershed.save("C:/sapyexamples/output/outwtrshd01")

Watershed example 2 (stand-alone script)

This example determines the contributing area for selected pour point locations on a flow direction Grid raster and outputs the watershed as a TIFF raster.

# Name: Watershed_Ex_02.py
# Description: Determines the contributing area above a set of cells in a
#     raster.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inFlowDirection = "flowdir"
inPourPointData = "pourpoint"
inPourPointField = "VALUE"

# Execute Watershed
outWatershed = Watershed(inFlowDirection, inPourPointData, inPourPointField)

# Save the output 
outWatershed.save("C:/sapyexamples/output/outwtrshd02.tif")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Pyramid, Scratch Workspace, Snap Raster, Tile Size