| 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:
| 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. Each point is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following:
| 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.
| 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. 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 |
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 |
Available with Spatial Analyst license.
Summary
Locates areas that are topographically lower than the surrounding terrain based on spatial characteristics.
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, and the downstream connection point, for all depressions included in the Output Depressions Polygons parameter value.
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 (max_connection_distance in Python) 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.
Parameters
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:
| 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. Each point is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following:
| 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.
| 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. 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 |
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
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", "", "", "", "", "")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"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set local variables
inRaster = "elevation.tif"
inRoadData = "roads.tif"
inMinDepth = "2 Meters"
inZUnit = "METERS"
inMinArea = "5 SquareMeters"
inMaxConnectionDist = "40 Meters"
inMaxRoadDist = "20 Meters"
# Execute the tool
outDepressions = LocateDepressions(inRaster, "", inRoadData, "", inMinDepth,
inZUnit, inMinArea, inMaxConnectionDist,
inMaxRoadDist)
# Save the output
outDepressions.save("C:/sapyexamples/output.gdb/outdepressions02")Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst