Locate Depressions (Spatial Analyst Tools)

Summary

Locates areas that are topographically lower than the surrounding terrain based on spatial characteristics.

Learn more about how Locate Depressions works

Usage

The Input Surface Raster (in_surface_raster in Python) parameter value can be a digital elevation model (DEM). Internally, depressions are identified based on the difference between the filled and original DEM.
Only depressions that meet all requirements set by the optional analysis parameters will be included in the Output Depressions Polygons (out_depressions_polygons in Python) parameter value.
The Output Connection Points (out_connection_points in Python) parameter value includes the point of lowest elevation within a depression for all depressions included in the Output Depressions Polygons parameter value.

It will also include the downstream connection point for each depression if a value is specified for the Maximum Distance to Connection (max_connection_distance in Python) parameter.
Specifying the Z Unit (z_unit in Python) parameter value ensures the proper computation of depression depth.

If a z-unit is available in the vertical coordinate system of the input surface 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 no value is specified, meter will be used by default.
The Maximum Distance to Connection parameter will consider the downstream connection to be the closest cell found that is of a lower elevation than the lowest elevation cell within the depression. If there are multiple cells that meet these criteria, the first one found will be returned.
The Maximum Distance to Roads (max_road_distance in Python) parameter can only be applied if the Input Raster or Feature Roads (in_road_data in Python) parameter is specified.
The map unit of the spatial reference of the Input Surface Raster parameter value is used to populate default units for the Minimum Area, Maximum Distance to Connection, and Maximum Distance to Roads parameters. If the unit identified by the Input Surface Raster parameter value does not match to both an available areal unit and linear unit, the parameters will default to Square Meters and Meters respectively.
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.

By default, this tool will use up to 50 percent of the available cores. You can control the number of cores the tool uses with the Parallel processing factor environment.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Label	Explanation	Data type
Input Surface Raster	The input surface raster.	Raster Layer
Output Depressions Polygons	The output feature class that will contain the identified depressions. Each depression polygon is uniquely numbered. Additional fields in the attribute table store specific information about the depression. Those fields are the following: `AREA`—The area of the depression in meters squared. `VOLUME`—The volume of the depression in meters cubed. `DIST_CON`—The distance to the downstream connection point in meters. This field will only be created if the Maximum Distance to Connection parameter value is specified. `DIST_ROAD`—The distance to the closest road in meters. This field is only created if a dataset is specified for the optional input roads data parameter.	Feature Class
Input Raster or Feature Roads (Optional)	The optional raster or feature dataset that defines roads. The roads can be defined by an integer or a floating-point raster, or by a point, line, or polygon feature.	Raster Layer; Feature Layer
Output Connection Points (Optional)	The optional output points that define the lowest elevation point in a depression and the corresponding downstream connection point. A downstream connection is defined as the closest cell of a lower elevation than the lowest elevation cell within a depression. The downstream connection point and related fields are only included in the output if a value is specified for the Maximum Distance to Connection parameter. Each point is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following: `DEP_ID`—The identifier of the depression the point is associated with. `POINT_TYPE`—Specifies whether the point is the lowest elevation point in the depression (= 0) or the downstream connection point (= 1). `POINT_ELEV`—The elevation of the point. `DIST_EDGE`—The distance to the edge of the depression in meters. `DIST_POINT`—The distance to the corresponding point in meters.	Feature Class
Minimum Depth (Optional)	The minimum depth allowed for a depression. Depressions with a maximum depth less than this value will not be included in the final output. The default is 0.05 meters or the equivalent in the specified z-unit.	Linear Unit
Z Unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. Inch—The linear unit will be inches. Foot—The linear unit will be feet. US Foot—The linear unit will be US survey feet. Yard—The linear unit will be yards. US Mile—The linear unit will be US survey 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.	String
Minimum Area (Optional)	The minimum area allowed for a depression. Area is the surface area of the top of the depression. Depressions with an area less than this value will not be included in the final output. The default is the total area of three cells or the equivalent in squared map units of the spatial reference for the Input Surface Raster parameter value.	Areal Unit
Maximum Distance to Connection (Optional)	The maximum distance allowed from the edge of a depression to the downstream connection point. A downstream connection is defined as the closest cell of a lower elevation than the lowest elevation cell within the depression. If the distance to a downstream connection is greater than this value, the depression will not be included in the final output. This parameter will only be applied if a value is specified for it.	Linear Unit
Maximum Distance to Roads (Optional)	The maximum distance allowed from the edge of a depression to the closest road. If a depression's distance from a road is greater than this value, it will not be included in the final output. The parameter is only available if a value for the Input Raster or Feature Roads parameter is provided. The default is 30 meters or the equivalent in the map unit of the spatial reference for the Input Surface Raster parameter value.	Linear Unit

LocateDepressions(in_surface_raster, out_depressions_polygons, {in_road_data}, {out_connection_points}, {min_depth}, {z_unit}, {min_area}, {max_connection_distance}, {max_road_distance})

Name	Explanation	Data type
in_surface_raster	The input surface raster.	Raster Layer
out_depressions_polygons	The output feature class that will contain the identified depressions. Each depression polygon is uniquely numbered. Additional fields in the attribute table store specific information about the depression. Those fields are the following: `AREA`—The area of the depression in meters squared. `VOLUME`—The volume of the depression in meters cubed. `DIST_CON`—The distance to the downstream connection point in meters. This field will only be created if the `max_connection_distance` parameter value is specified. `DIST_ROAD`—The distance to the closest road in meters. This field is only created if a dataset is specified for the optional input roads data parameter.	Feature Class
in_road_data (Optional)	The optional raster or feature dataset that defines roads. The roads can be defined by an integer or a floating-point raster, or by a point, line, or polygon feature.	Raster Layer; Feature Layer
out_connection_points (Optional)	The optional output points that define the lowest elevation point in a depression and the corresponding downstream connection point. A downstream connection is defined as the closest cell of a lower elevation than the lowest elevation cell within a depression. The downstream connection point and related fields are only included in the output if a value is specified for the `max_connection_distance` parameter. Each point is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following: `DEP_ID`—The identifier of the depression the point is associated with. `POINT_TYPE`—Specifies whether the point is the lowest elevation point in the depression (= 0) or the downstream connection point (= 1). `POINT_ELEV`—The elevation of the point. `DIST_EDGE`—The distance to the edge of the depression in meters. `DIST_POINT`—The distance to the corresponding point in meters.	Feature Class
min_depth (Optional)	The minimum depth allowed for a depression. Depressions with a maximum depth less than this value will not be included in the final output. The default is 0.05 meters or the equivalent in the specified z-unit.	Linear Unit
z_unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. `INCH`—The linear unit will be inches. `FOOT`—The linear unit will be feet. `FOOT_US`—The linear unit will be US survey feet. `YARD`—The linear unit will be yards. `MILE_US`—The linear unit will be US survey 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.	String
min_area (Optional)	The minimum area allowed for a depression. Area is the surface area of the top of the depression. Depressions with an area less than this value will not be included in the final output. The default is the total area of three cells or the equivalent in squared map units of the spatial reference for the `in_surface_raster` parameter value.	Areal Unit
max_connection_distance (Optional)	The maximum distance allowed from the edge of a depression to the downstream connection point. A downstream connection is defined as the closest cell of a lower elevation than the lowest elevation cell within the depression. If the distance to a downstream connection is greater than this value, the depression will not be included in the final output. This parameter will only be applied if a value is specified for it.	Linear Unit
max_road_distance (Optional)	The maximum distance allowed from the edge of a depression to the closest road. If a depression's distance from a road is greater than this value, it will not be included in the final output. The parameter is only available if a value for the `in_road_data` parameter is provided. The default is 30 meters or the equivalent in the map unit of the spatial reference for the `in_surface_raster` parameter value.	Linear Unit

Code sample

LocateDepressions example 1 (Python window)

This example shows how to use Locate Depressions to locate depressions from an input surface raster with no prior sink filling.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/arcpyexamples/data.gdb"
outDepressions = LocateDepressions("elevation", "outdepressions01.shp", "",
                                    "outpoints01.shp", "", "", "", "", "")

LocateDepressions example 2 (stand-alone script)

This example locates depressions from an input surface with no prior sink filling and real depressions.

# Name: LocateDepressions_standalone.py
# Description: Locates depressions that meet the specified criteria.
# Requirements: Spatial Analyst extension

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

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

# Set local variables
inRaster = "elevation.tif"
inRoadData = "roads.tif"
inMinDepth = "2 Meters"
inZUnit = "METERS"
inMinArea = "5 SquareMeters"
inMaxConnectionDist = "40 Meters"
inMaxRoadDist = "20 Meters"

# Run the tool
outDepressions = LocateDepressions(inRaster, "", inRoadData, "", inMinDepth,
                                    inZUnit, inMinArea, inMaxConnectionDist,
                                    inMaxRoadDist)

# Save the output
outDepressions.save("C:/sapyexamples/output.gdb/outdepressions02")

Environments

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

Licensing information