Topo to Raster by File (Spatial Analyst)
Summary
Interpolates a hydrologically correct raster surface from point, line, and polygon data using parameters specified in a file.
Usage
-
The parameter file is structured with the input datasets listed first, followed by the various parameter settings, then the output options.
The input data identifies the input datasets and, where applicable, fields. There are six types of input: Contours, Points, Sinks, Streams, Lakes, and Boundaries. You can use as many inputs as you want, within reason. The order in which the inputs are entered does not have any bearing on the outcome. <Path> indicates a path to a dataset, <Item> indicates a field name, and <#> indicates a value to be entered.
The following table lists all of the parameters, the definition of each, and their syntax.
Parameter
Definition
Syntax
Contours
Contour line dataset with item containing height values.
Contour <Path> <Item> Points
Point dataset with item containing height values.
Point <Path> <Item> Sinks
Point dataset containing sink locations. If the dataset has elevation values for the sinks, specify that field name as the <Item>. If only the locations of the sinks are to be used, use NONE for <Item>.
Sink <Path> <Item> Streams
Stream line dataset. Height values are not necessary.
Stream <Path> Lakes
Lake polygon dataset. Height values are not necessary.
Lake <Path> Boundary
Boundary polygon dataset. Height values are not necessary.
Boundary <Path> Enforce
Controls whether drainage enforcement is applied.
ENFORCE <ON | OFF | ON_WITH_SINK> Datatype
Primary type of input data.
DATATYPE <CONTOUR | SPOT> Iterations
The maximum number of iterations the algorithm performs.
ITERATIONS <#> Roughness Penalty
The measure of surface roughness.
ROUGHNESS_PENALTY <#> Discretization Error Factor
The amount to adjust the data smoothing of the input data into a raster.
DISCRETE_ERROR_FACTOR <#> Vertical Standard Error
The amount of random error in the z-values of the input data.
VERTICAL_STANDARD_ERROR <#> Tolerances
The first reflects the accuracy of elevation data in relation to surface drainage, and the other prevents drainage clearance through unrealistically high barriers.
TOLERANCES <#> <#> Z-Limits
Lower and upper height limits.
ZLIMITS <#> <#> Extent
Minimum x, minimum y, maximum x, and maximum y coordinate limits.
EXTENT <#> <#> <#> <#> Cell Size
The resolution of the final output raster.
CELL_SIZE <#> Margin
Distance in cells to interpolate beyond the specified output extent and boundary.
MARGIN <#> Output Stream Features
Only use if Output stream polyline features is set in the Topo to Raster by File dialog box.
OUT_STREAM Output Sink Features
Only use if Output remaining sink point features is set in the Topo to Raster by File dialog box.
OUT_SINK Output Diagnostics File
The location and name of the diagnostics file.
OUT_DIAGNOSTICS <Path> -
Do not specify pathnames for the optional output feature datasets in the parameter file. Use the Output stream polyline features and Output remaining sink point features in the tool dialog box to identify these outputs.
-
The contents of an example parameter file are:
Contour D:\data\contours2\arc HEIGHT Point D:\data\points2\point SPOTS Sink D:\data\sinks_200.shp Stream D:\data\streams\arc Lake D:\data\lakes\polygon Boundary D:\data\clipcov\polygon ENFORCE ON DATATYPE CONTOUR ITERATIONS 40 ROUGHNESS_PENALTY 0.00000000000 DISCRETE_ERROR_FACTOR 1.00000000000 VERTICAL_STANDARD_ERROR 0.00000000000 TOLERANCES 2.50000000000 100.00000000000 ZLIMITS -2000.00000000000 13000.00000000000 EXTENT -810480.62500000000 8321785.00000000000 810480.62500000000 10140379.00000000000 CELL_SIZE 1800.00000000000 MARGIN 20 OUT_STREAM OUT_SINK OUT_DIAGNOSTICS D:\data\ttr_diag.txt
Syntax
| Parameter | Explanation | Data Type |
in_parameter_file |
The input ASCII text file containing the inputs and parameters to use for the interpolation. The file is typically created from a previous run of Topo to Raster with the optional output parameter file specified. In order to test the outcome of changing the parameters, it is easier to make edits to this file and rerun the interpolation than to correctly issue the Topo to Raster tool each time. | File |
out_stream_features (Optional) |
Output feature class of stream polyline features. | Feature Class |
out_sink_features (Optional) |
Output feature class of remaining sink point features. | 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 a parameter file defining the input point, line, and polygon data.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outTTRByFile = TopoToRasterByFile("topotorasterbyfile.txt",
"C:/sapyexamples/output/out_streams.shp")
outTTRByFile.save("C:/sapyexamples/output/ttrbyfout.tif")
This example creates a hydrologically correct GRID surface raster from a parameter file defining the input point, line, and polygon data.
# Name: TopoToRasterByFile_Ex_02.py
# Description: Interpolates a hydrologically correct
# surface from point, line, and polygon data using
# parameters specified in a file.
# Requirements: Spatial Analyst Extension
# Author: ESRI
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Set environment settings
env.workspace = "C:/sapyexamples/data"
# Set local variables
inParameterFile = "topotorasterbyfile.txt"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute TopoToRasterByFile
outTTRByFile = TopoToRasterByFile(inParameterFile)
# Save the output
outTTRByFile.save("C:/sapyexamples/output/ttrbyfout02")