Adjust Raster to Stream (Spatial Analyst Tools)

Summary

Modifies the cell values of an input surface raster at specified locations.

Usage

The Output Surface Raster (out_surface_raster in Python) parameter value will contain modified cell values only along the input paths. All other cells retain their original values from the input surface raster.
The Input Path Features (in_path_features in Python) parameter value represents the locations where cell values will be modified. Both 2D and 3D lines are supported. If 2D lines are specified, the cell values will be extracted from the input surface raster and stored in the vertices on the optional 3D output path features. If 3D lines are specified, the Z values of the vertices will be used to modify the cell values.
The tool processes each line independently and uses the same input surface raster for each.

If two lines overlap, the last processed line will have the strongest influence.

If two lines meet (for example, at a junction), the tool will process them one by one. If the input path features are 3D lines and the Z values stored at each junction vertex are not consistent, the modified cell value may not ensure downstream flow.
When the Modification Method (modification_method in Python) parameter is set to the All option (ALL in Python), the tool will use the Z values of all available vertices.

The number of vertices does not have to match the number of cells beneath the line. If the number does not match, the tool will interpolate. If they are the same, no interpolation will happen and the tool will modify each cell according to the Z value of each vertex.

This method will not modify the input surface raster if the Input Path Features parameter value was created using the Generate Breach Lines tool and the same elevation raster is used in both tools or the input path features are a 2D line that has the same number of vertices as cells beneath it.
When a value larger than the analysis cell size is specified for the Modification Width (modification_width in Python) parameter, the tool will breach the path creating a channel with a V-shape cross-section. For a fractional width (for example, 1.5 cells), the tool will round up to the largest integer.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Label	Explanation	Data type
Input Path Features	The input polyline features that identifies locations at which the cell values will be modified. The input can be a 2D or 3D line.	Feature Layer
Input Surface Raster	The input surface raster.	Raster Layer
Output Path Features (Optional)	A 3D representation of the input path features. The polyline vertices at each cell center of the Input Surface Raster parameter value will contain the lowest elevation within the path as Z values in the 3D shape.	Feature Dataset
Modification Method (Optional)	Specifies the method that will be used to modify the cell values of the surface raster. Endpoints—The start and end vertices Z value will be used to interpolate. This is the default. All—All available vertices Z value will be used for modification. Maximum—The maximum Z value across all the vertices will be used to modify all cells beneath the path. Minimum—The minimum Z value across all the vertices will be used to modify all cells beneath the path. Average—The average Z value across all the vertices will be calculated and used to modify all cells beneath the path.	String
Modification Width (Optional)	The width of the modified path in the input surface raster. By default, it will be the analysis cell size. The channel cross-section will be V shaped.	Linear Unit
Endpoints Buffer (Optional)	The buffer that will be used at the start and end of the input path line. The buffer ensures a smooth transition between the surface raster and the start and end of the path line.	Linear Unit

Return value

Label	Explanation	Data type
Output Surface Raster	The output surface raster whose cell values along the input paths were modified.	Raster

AdjustRasterToStream(in_path_features, in_surface_raster, {out_path_features}, {modification_method}, {modification_width}, {endpoints_buffer})

Name	Explanation	Data type
in_path_features	The input polyline features that identifies locations at which the cell values will be modified. The input can be a 2D or 3D line.	Feature Layer
in_surface_raster	The input surface raster.	Raster Layer
out_path_features (Optional)	A 3D representation of the input path features. The polyline vertices at each cell center of the `in_surface_raster` parameter value will contain the lowest elevation within the path as Z values in the 3D shape.	Feature Dataset
modification_method (Optional)	Specifies the method that will be used to modify the cell values of the surface raster. `ENDPOINTS`—The start and end vertices Z value will be used to interpolate. This is the default. `ALL`—All available vertices Z value will be used for modification. `MAXIMUM`—The maximum Z value across all the vertices will be used to modify all cells beneath the path. `MINIMUM`—The minimum Z value across all the vertices will be used to modify all cells beneath the path. `AVERAGE`—The average Z value across all the vertices will be calculated and used to modify all cells beneath the path.	String
modification_width (Optional)	The width of the modified path in the input surface raster. By default, it will be the analysis cell size. The channel cross-section will be V shaped.	Linear Unit
endpoints_buffer (Optional)	The buffer that will be used at the start and end of the input path line. The buffer ensures a smooth transition between the surface raster and the start and end of the path line.	Linear Unit

Return value

Name	Explanation	Data type
out_surface_raster	The output surface raster whose cell values along the input paths were modified.	Raster

Code sample

AdjustRasterToStream example 1 (Python window)

This example generates a modified surface raster along the input stream lines with default parameter values.

from arcpy.sa import *
out_modified_surface = AdjustRasterToStream("in_breach_lines", 
                                             "surface.tif", 
                                             None, 
                                             "ENDPOINTS", 
                                             "", 
                                             "")
out_modified_surface.save("C:/arcpyExamples/outputs/" \
                            "out_modified_surface.tif")

AdjustRasterToStream example 2 (stand-alone script)

This example generates a modified surface raster along the input stream lines using the minimum Z value across all vertices.

# Name: AdjustRasterToStream_standalone.py
# Description: Adjusts the cell values of a surface raster along the input 2D stream 
# or lines to the minimum Z value across all the vertices. 
# Additionally, it creates an output shapefile representing the input streams in 3D.
# Requirements: Spatial Analyst extension

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

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

# Set the local variables
in_path_features = "breachlines.shp"
in_surface_raster = "surface.tif"
out_3d_path_features = "breachlines_3D.shp"

# Run Adjust Raster to Stream
out_surface_raster = AdjustRasterToStream(in_path_features, 
                                           in_surface_raster, 
                                           out_3d_path_features, 
                                           "MIN", 
                                           "", 
                                           "")

# Save the output
out_surface_raster.save("C:/arcpyExamples/outputs/out_modified_surface.tif")

Environments

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

Licensing information

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

Adjust Raster to Stream (Spatial Analyst Tools)

Summary

Usage

Parameters

Return value

Environments

Licensing information

Related topics