Generate Breach Lines (Spatial Analyst Tools)

Summary

Creates lines used for breaching local impediments of water flow.

Usage

A depression is a topographically lower area than the surrounding terrain that disrupts water flow. The Generate Breach Lines tool finds a breaching line that connects the depression to a downstream point ensuring hydrologic connectivity.
The Output Breach Lines parameter value represents the lines that breach each depression polygon ensuring hydrologic connectivity. The Input Depression Polygons (in_depression_polygons in Python) parameter value represents each depression polygon to breach.
The Input Connection Points (in_connection_points in Python) parameter value represents the start and end points that the breach line will connect. It can be created using the Locate Depressions tool.
The Input Connection Points feature layer is expected to have two fields. The first field, DEP_ID, is the ID of the depression that point belongs to. The binary field POINT_TYPE designates whether the point marks the start (value 0) or the end (value 1) of the line to generate.
The breach lines in the output feature layer always start at a point within the depression and end at a cell location with a lower elevation to ensure that water will flow. The tool does not create lines that partially cover this path. In other words, no partial or incomplete lines are created.
For each depression polygon, the output breach line starts at the minimum elevation point within the depression. The end of the line depends on the option specified for Trace Method (trace_method in Python) parameter value.
When the Shortest Path (SHORTEST_PATH in Python) option is specified for Trace Method parameter value, both start and end points are required to be present in the Input Connection Points parameter value for each depression.
When the Minimum Breaching Cost (MIN_BREACHING_COST in Python) option is specified for Trace Method, the output breach line represents the path which minimizes the path breaching cost following Lindsay and Dhun (2015). Breach cost is equal to the amount of elevation to lower or carve to create a channel connecting the depression to another cell location at a lower elevation to ensure water flow.
If the Mask environment setting is specified, the tool will generate a breach line only if the start point (within the depression) is within the mask area. The depression area can be fully or partially within the mask area.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Label	Explanation	Data type
Input Depression Polygons	The input feature layer that contains polygons defining depression areas. A depression is a topographically lower area than the surrounding terrain that disrupts water flow.	Feature Layer
Input Surface Raster	The input surface raster.	Raster Layer
Output Breach Lines	The output feature class that will contain a line that connects depressions with a downstream cell and ensures hydrologic connectivity. Each line is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following: `LENGTH`—The length of the breach line in meters. `DEP_ID`—The identifier of the depression the line is associated with. `START_X`—The X coordinate of the start of the breach line. `START_Y`—The Y coordinate of the start of the breach line. `END_X`—The X coordinate of the end of the breach line. `END_Y`—The Y coordinate of the end of the breach line. The values of the four coordinate fields are in the output spatial reference.	Feature Class
Input Connection Points (Optional)	The optional input points that define the lowest elevation point in a depression and the corresponding downstream connection point. This input is required when Shortest Path is specified for the Trace Method parameter value. Expected fields in the attribute table are: `DEP_ID`—The identifier of the depression the point is associated with. `POINT_TYPE`—A Boolean field where the value 0 specifies that the point is the lowest elevation point in the depression and the value 1 specifies that is a downstream connection point.	Feature Layer
Trace Method (Optional)	Specifies the method that used to construct the breach line. The available methods are the following: Minimum Breaching Cost—The line will follow a path which minimizes the breaching cost. This is the default. Shortest Path—The path with the shortest distance between the start and end. It requires both start and end points to be present in the Input Connection Points parameter value. The path will be the shortest line that breaches the local impediment to water flow. Minimum Elevation Change—The line will follow a path that minimizes elevation change.	String
Maximum Length (Optional)	The maximum length allowed for a breach line. If a potential breach line is above this limit, that line will not be included in the output breach lines feature class. The default is 50 Meters or the equivalent in the map units of the analysis spatial reference.	Linear Unit

GenerateBreachLines(in_depression_polygons, in_surface_raster, out_breach_lines, {in_connection_points}, {trace_method}, {max_length})

Name	Explanation	Data type
in_depression_polygons	The input feature layer that contains polygons defining depression areas. A depression is a topographically lower area than the surrounding terrain that disrupts water flow.	Feature Layer
in_surface_raster	The input surface raster.	Raster Layer
out_breach_lines	The output feature class that will contain a line that connects depressions with a downstream cell and ensures hydrologic connectivity. Each line is uniquely numbered. Additional fields in the attribute table store specific information about the point. Those fields are the following: `LENGTH`—The length of the breach line in meters. `DEP_ID`—The identifier of the depression the line is associated with. `START_X`—The X coordinate of the start of the breach line. `START_Y`—The Y coordinate of the start of the breach line. `END_X`—The X coordinate of the end of the breach line. `END_Y`—The Y coordinate of the end of the breach line. The values of the four coordinate fields are in the output spatial reference.	Feature Class
in_connection_points (Optional)	The optional input points that define the lowest elevation point in a depression and the corresponding downstream connection point. This input is required when `SHORTEST_PATH` is specified for the `trace_method` parameter value. Expected fields in the attribute table are the following: `DEP_ID`—The identifier of the depression the point is associated with. `POINT_TYPE`—A Boolean field where the value 0 specifies that the point is the lowest elevation point in the depression and the value 1 specifies that is a downstream connection point.	Feature Layer
trace_method (Optional)	Specifies the method that used to construct the breach line. The available methods are the following: `MIN_BREACHING_COST`—The line will follow a path which minimizes the breaching cost. This is the default. `SHORTEST_PATH`—The path with the shortest distance between the start and end. It requires both start and end points to be present in the `in_connection_points` parameter value. The path will be the shortest line that breaches the local impediment to water flow. `MIN_ELEV`—The line will follow a path that minimizes elevation change.	String
max_length (Optional)	The maximum length allowed for a breach line. If a potential breach line is above this limit, that line will not be included in the output breach lines feature class. The default is 50 Meters or the equivalent in the map units of the analysis spatial reference.	Linear Unit

Code sample

GenerateBreachLines example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window. This example generates the shortest distance line that breaches the depression polygon connecting the start and end connection points with default parameter values.

from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapy/examples/data"
GenerateBreachLines("inputDepressionPolygons.shp", "inputSurfaceRaster.tif", "C:/sapyexamples/output/streams.shp", "", "", "", "")

GenerateBreachLines example 2 (stand-alone script)

This example generates the lines that breaches the depression polygon with a maximum length of 50 meters which follow the minimum elevation path.

# Name: GenerateBreachLines_standalone.py
# Description: Generates lines that breach depression polygons following the 
#              minimum elevation path and a maximum length of 50 meters.
# Requirements: Spatial Analyst extension

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

# Set the analysis environments
env.workspace = "C:/sapyexamples/data"

# Set the local variables
in_depression_polygons = "depressions.shp",
in_surface_raster = "inSurfaceRaster.tif"
out_breach_lines = "C:/sapyexamples/output/breachlines.shp"
in_connection_points= None
trace_method = "MIN_BREACHING_COST"
max_length = "50 Meters"


# Run Generate Breach Lines
GenerateBreachLines(in_depression_polygons, 
                    in_surface_raster,
                    out_breach_lines,
                    in_connection_points,
                    trace_method,
                    max_length)

Environments

Extent, Mask, Auto Commit, Current Workspace, Default Output Z Value, Geographic Transformations, M Resolution, M Tolerance, Output CONFIG Keyword, Output Coordinate System, Output has M values, Output has Z values, Output M Domain, Output XY Domain, Output Z Domain, Scratch Workspace, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance

Licensing information

Basic: Requires Spatial Analyst
Standard: Requires Spatial Analyst
Advanced: Requires Spatial Analyst

References

"Lindsay J, Dhun K. 2015. Modelling surface drainage patterns in altered landscapes using LiDAR. International Journal of Geographical Information Science, 29: 1-15. DOI: 10.1080/13658816.2014.975715"