Topo to Raster (Spatial Analyst)
Summary
Interpolates a hydrologically correct raster surface from point, line, and polygon data.
Usage
-
The best results will be obtained if all input data is stored in the same planar coordinate system and has the same ZUnits. Unprojected data (latitude-longitude) can be used; however, the results may not be as accurate, particularly at high latitudes.
-
If more than one input point falls within an output cell,Topo to Raster will use the average value for the interpolation (only the first 100 points that fall within a cell will be considered and the rest will be ignored). If too many points are encountered by the algorithm, an error may occur, indicating the point dataset has too many points. The maximum number of points that can be used is NRows * NCols, where NRows is the number of rows in the output raster and NCols is the number of columns.
-
When the input feature type is CONTOUR, the algorithm first generates a generalized morphology of the surface based on the curvature of the contours. The algorithm then implements the contours as a source of elevation information. Contours are best suited for large-scale data where the contours and corners are reliable indicators of streams and ridges. At smaller scales it can be just as effective, and less expensive, to digitize corner points of contours and use them as an input point feature class.
-
Representing braided streams or using arcs to represent two sides of a stream may not produce reliable results. Stream data always takes priority over point or contour data; therefore, elevation data points that conflict with descent down each stream are ignored. Stream data is a powerful way of adding topographic information to the interpolation, further ensuring the quality of the output DEM.
-
Typical values for the Tolerance 1 and Tolerance 2 settings are:
- For point data at 1:100,000 scale, use 5.0 and 200.0.
- For less dense point data up to 1:500,000 scale, use 10.0 and 400.0.
- For contour data with contour spacing of 10, use 5.0 and 100.0.
Tolerance 2 should be at least 6 times greater than Tolerance 1.
-
To make experimentation with the inputs and parameters easier, use the Topo to Raster dialog box to create an output parameter file, which can be modified in any text editor and used as input to the Topo to Raster by File tool.
Topo to Raster is a memory-intensive application and it is therefore not possible to create large output rasters. When large output is required, use the MARGIN parameter.
Syntax
| Parameter | Explanation | Data Type |
in_topo_features topo_input |
The Topo class specifies the input features containing the z-values to be interpolated into a surface raster. There are nine types of data accepted inputs to the Topo class: TopoPointElevation, TopoContour, TopoStream, TopoSink, TopoBoundary, TopoLake, TopoCliff, TopoExclusion, and TopoCoast.
The PointElevation, Contour, and Sink types of feature input can have a field specified that contains the z-values. There is no Field option for Boundary, Lake, Cliff, Coast, Exclusion, or Stream input types. | TopoInput |
cell_size (Optional) |
The cell size at which the output raster will be created. This will be the value in the environment if it is explicitly set; otherwise, it is the shorter of the width or the height of the extent of the input point features, in the input spatial reference, divided by 250. | Analysis Cell Size |
extent (Optional) |
The Extent class determines the extent for the output raster dataset. Interpolation will occur out to the x and y limits, and cells outside that extent will be NoData. For best interpolation results along the edges of the output raster, the x and y limits should be smaller than the extent of the input data by at least 10 cells on each side. The form of the Extent class is:
The default extent is the largest of all extents of the input feature data. | Extent |
Margin margin (Optional) |
Distance in cells to interpolate beyond the specified output extent and boundary. The value must be greater than or equal to 0 (zero). The default value is 20. If the Extent and TopoBoundary feature dataset are the same as the limit of the input data (the default), values interpolated along the edge of the DEM will not match well with adjacent DEM data. This is because they have been interpolated using one-half as much data as the points inside the raster, which are surrounded on all sides by input data. The Margin option allows input data beyond these limits to be used in the interpolation. | Long |
minimum_z_value (Optional) |
The minimum z-value to be used in the interpolation. The default is 20 percent below the smallest of all the input values. | Double |
maximum_z_value (Optional) |
The maximum z-value to be used in the interpolation. The default is 20 percent above the largest of all input values. | Double |
enforce (Optional) |
The type of drainage enforcement to apply. The drainage enforcement option can be set to attempt to remove all sinks or depressions so a hydrologically correct DEM can be created. If sink points have been explicitly identified in the input feature data, these depressions will not be filled.
| String |
data_type (Optional) |
The dominant elevation data type of the input feature data.
Specifying the relevant selection optimizes the search method used during the generation of streams and ridges. | String |
maximum_iterations (Optional) |
The maximum number of interpolation iterations. The number of iterations must be greater than zero. A default of 20 is normally adequate for both contour and line data. A value of 30 will clear fewer sinks. Rarely, higher values (45–50) may be useful to clear more sinks or to set more ridges and streams. Iteration ceases for each grid resolution when the maximum number of iterations has been reached. | Long |
roughness_penalty (Optional) |
The integrated squared second derivative as a measure of roughness. The roughness penalty must be zero or greater. If the primary input data type is CONTOUR, the default is zero. If the primary data type is SPOT, the default is 0.5. Larger values are not normally recommended. | Double |
discrete_error_factor (Optional) |
The discrete error factor is used to adjust the amount of smoothing when converting the input data to a raster. The value must be greater than zero. The normal range of adjustment is 0.25 to 4, and the default is 1. A smaller value results in less data smoothing; a larger value causes greater smoothing. | Double |
vertical_standard_error (Optional) |
The amount of random error in the z-values of the input data. The value must be zero or greater. The default is zero. The vertical standard error may be set to a small positive value if the data has significant random (non-systematic) vertical errors with uniform variance. In this case, set the vertical standard error to the standard deviation of these errors. For most elevation datasets, the vertical error should be set to zero, but it may be set to a small positive value to stabilize convergence when rasterizing point data with stream line data. | Double |
tolerance_1 (Optional) |
This tolerance reflects the accuracy and density of the elevation points in relation to surface drainage. For point datasets, set the tolerance to the standard error of the data heights. For contour datasets, use one-half the average contour interval. The value must be zero or greater. The default is 2.5 if the data type is CONTOUR and zero if the data type is SPOT. | Double |
tolerance_2 (Optional) |
This tolerance prevents drainage clearance through unrealistically high barriers. The value must be greater than zero. The default is 100 if the data type is CONTOUR and 200 if the data type is SPOT. | Double |
out_stream_features (Optional) | The output line feature class of stream polyline features and ridge line features. The line features are created at the beginning of the interpolation process. It provides the general morphology of the surface for interpolation. It can be used to verify correct drainage and morphology by comparing known stream and ridge data. The polyline features are coded as follows:
| Feature Class |
out_sink_features (Optional) |
The output point feature class of the remaining sink point features. These are the sinks that were not specified in the sink input feature data and were not cleared during drainage enforcement. Adjusting the values of the tolerances, tolerance_1 and tolerance_2, can reduce the number of remaining sinks. Remaining sinks often indicate errors in the input data that the drainage enforcement algorithm could not resolve. This can be an efficient way of detecting subtle elevation errors. | Feature Class |
out_diagnostic_file (Optional) |
The output diagnostic file listing all inputs and parameters used and the number of sinks cleared at each resolution and iteration. | File |
out_parameter_file (Optional) |
The output parameter file listing all inputs and parameters used, which can be used with Topo to Raster by File to run the interpolation again. | File |
profile_penalty (Optional) |
The profile curvature roughness penalty is a locally adaptive penalty that can be used to partly replace total curvature. It can yield good results with high-quality contour data but can lead to instability in convergence with poor data. Set to 0.0 for no profile curvature (the default), set to 0.5 for moderate profile curvature, and set to 0.8 for maximum profile curvature. Values larger than 0.8 are not recommended and should not be used. | Double |
out_residual_feature (Optional) |
The output point feature class of all the large elevation residuals as scaled by the local discretisation error. All the scaled residuals larger than 10 should be inspected for possible errors in input elevation and stream data. Large-scaled residuals indicate conflicts between input elevation data and streamline data. These may also be associated with poor automatic drainage enforcements. These conflicts can be remedied by providing additional streamline and/or point elevation data after first checking and correcting errors in existing input data. Large unscaled residuals usually indicate input elevation errors. | Feature Class |
out_stream_cliff_error_feature (Optional) |
The output point feature class of locations where possible stream and cliff errors occur. The locations where the streams have closed loops, distributaries, and streams over cliffs can be identified from the point feature class. Cliffs with neighboring cells that are inconsistent with the high and low sides of the cliff are also indicated. This can be a good indicator of cliffs with incorrect direction. Points are coded as follows:
| Feature Class |
out_contour_error_feature (Optional) |
The output point feature class of possible errors pertaining to the input contour data. Contours with bias in height exceeding five times the standard deviation of the contour values as represented on the output raster are reported to this feature class. Contours that join other contours with a different elevation are flagged in this feature class by the code 1; this is a sure sign of a contour label error. | Feature Class |
Return Value
| Name | Explanation | Data Type |
| out_surface_raster |
The output interpolated surface raster. | Raster |
Code Sample
This example creates a hydrologically correct TIFF surface raster from point, line, and polygon data.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outTTR = TopoToRaster([TopoPointElevation([['spots', 'spot_meter']]),
TopoContour([['contours', 'spot_meter']]),
TopoCliff(['cliff'])], 60,
"#", "#", "#", "#", "NO_ENFORCE")
outTTR.save("C:/sapyexamples/output/ttrout.tif")
This example creates a hydrologically correct Grid surface raster from point, line, and polygon data.
# Name: TopoToRaster_Ex_02.py
# Description: Interpolates a hydrologically correct surface
# from point, line, and polygon data.
# 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
inPointElevations = TopoPointElevation([['spots.shp', 'spot_meter'],
['spots2.shp', 'elev']])
inBoundary = TopoBoundary(['boundary.shp'])
inContours = TopoContour([['contours.shp', 'spot_meter']])
inLake = TopoLake(['lakes.shp'])
inSinks = TopoSink([['sink1.shp', 'elevation'], ['sink2.shp', 'none']])
inStream = TopoStream(['streams.shp'])
inCliff = TopoCliff(['cliff.shp'])
inCoast = TopoCoast(['coast.shp'])
inExclusion = TopoExclusion(['ignore.shp'])
inFeatures = ([inPointElevations, inContours, inLake, inStream, inBoundary, inSinks, inCliff, inCoast, inExclusion])
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute TopoToRaster
outTTR = TopoToRaster(inFeatures)
# Save the output
outTTR.save("C:/sapyexamples/output/ttrout03")