Back to Top

Topo to Raster by File (Spatial Analyst)

In this topic

  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information

Available with Spatial Analyst license.

Available with 3D Analyst license.

Summary

Interpolates a hydrologically correct raster surface from point, line, and polygon data using parameters specified in a file.

Learn more about how Topo to Raster works

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 nine types of input: Contours, Points, Sinks, Streams, Lakes, Boundaries, Cliffs, Exclusion, and Coastal polygons. 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.

    ParameterDefinitionSyntax

    Input datasets:

    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>

    Cliff

    Line dataset of the cliffs. There is no Field option for Cliff.

    		Cliff <Path>

    Exclusion

    Exclusion polygon dataset of the areas in which the input data should be ignored. There is no Field option for Exclusion.

    		Exclusion <Path>

    Coast

    Coast polygon dataset containing the outline of a coastal area. There is no Field option for Coast.

    		Boundary <Path>

    Parameter settings:

    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 <#>

    Profile curvature roughness penalty

    The profile curvature roughness penalty is a locally adaptive penalty that can be use to partly replace total curvature.

    		PROFILE_PENALTY <#>

    Discretisation 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 <#>

    Outputs:

    Output stream features

    The output line feature class of stream polyline features and ridge line features.

    		OUT_STREAM

    Output sink features

    The output point feature class of the remaining sink point features.

    		OUT_SINK

    Output diagnostics file

    The location and name of the diagnostics file.

    		OUT_DIAGNOSTICS <Path>

    Output residual point features

    The output point feature class of all the large elevation residuals as scaled by the local discretisation error.

    		OUT_RESIDUALS

    Output stream and cliff point features

    The output point feature class of locations where possible stream and cliff errors occur.

    		OUT_STREAM_CLIFF_ERRORS

    Output contour error point features

    The output point feature class of possible errors pertaining to the input contour data.

    		OUT_CONTOUR_ERRORS

  • For data formats that support Null values, such as file geodatabase feature classes, a Null value will be ignored when used as input.

  • Do not specify paths 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
     Cliff D:\data\cliffs.shp 
     ENFORCE ON
     DATATYPE CONTOUR
     ITERATIONS 40
     ROUGHNESS_PENALTY 0.0
     PROFILE_PENALTY 0.5
     DISCRETE_ERROR_FACTOR 1.0
     VERTICAL_STANDARD_ERROR 0.0
     TOLERANCES 2.5 100.0
     ZLIMITS -2000.0 13000.0
     EXTENT -810480.625 8321785.0 810480.625 10140379.0
     CELL_SIZE 1800.00000000000
     MARGIN 20
     OUT_DIAGNOSTICS D:\data\ttr_diag.txt

  • See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

DialogPython

LabelExplanationData Type
Input 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
Output stream polyline features
(Optional)

Output feature class of stream polyline features.

The polyline features are coded as follows:

1. Input stream line not over cliff.

2. Input stream line over cliff (waterfall).

3. Drainage enforcement clearing a spurious sink.

4. Stream line determined from contour corner.

5. Ridge line determined from contour corner.

6. Code not used.

7. Data stream line side conditions.

8. Code not used.

9. Line indicating large elevation data clearance.

Feature Class
Output remaining sink point features
(Optional)

Output feature class of remaining sink point features.

Feature Class
Output residual point features
(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
Output stream and cliff error point features
(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:

1. True circuit in data streamline network.

2. Circuit in stream network as encoded on the out raster.

3. Circuit in stream network via connecting lakes.

4. Distributaries point.

5. Stream over a cliff (waterfall).

6. Points indicating multiple stream outflows from lakes.

7. Code not used.

8. Points beside cliffs with heights inconsistent with cliff direction.

9. Code not used.

10. Circular distributary removed.

11. Distributary with no inflowing stream.

12. Rasterized distributary in output cell different to where the data stream line distributary occurs.

13. Error processing side conditions—an indicator of very complex streamline data.

Feature Class
Output contour error point features
(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

LabelExplanationData Type
Output surface raster

The output interpolated surface raster.

It is always a floating-point raster.

Raster

TopoToRasterByFile(in_parameter_file, {out_stream_features}, {out_sink_features}, {out_residual_feature}, {out_stream_cliff_error_feature}, {out_contour_error_feature})
NameExplanationData 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.

The polyline features are coded as follows:

1. Input stream line not over cliff.

2. Input stream line over cliff (waterfall).

3. Drainage enforcement clearing a spurious sink.

4. Stream line determined from contour corner.

5. Ridge line determined from contour corner.

6. Code not used.

7. Data stream line side conditions.

8. Code not used.

9. Line indicating large elevation data clearance.

Feature Class
out_sink_features
(Optional)

Output feature class of remaining sink point features.

Feature Class
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:

1. True circuit in data streamline network.

2. Circuit in stream network as encoded on the out raster.

3. Circuit in stream network via connecting lakes.

4. Distributaries point.

5. Stream over a cliff (waterfall).

6. Points indicating multiple stream outflows from lakes.

7. Code not used.

8. Points beside cliffs with heights inconsistent with cliff direction.

9. Code not used.

10. Circular distributary removed.

11. Distributary with no inflowing stream.

12. Rasterized distributary in output cell different to where the data stream line distributary occurs.

13. Error processing side conditions—an indicator of very complex streamline data.

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

NameExplanationData Type
out_surface_raster

The output interpolated surface raster.

It is always a floating-point raster.

Raster

Code sample

TopoToRasterByFile example 1 (Python window)

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", "#",
                   "C:/sapyexamples/output/out_resids.shp")
outTTRByFile.save("C:/sapyexamples/output/ttrbyfout.tif")
TopoToRasterByFile example 2 (stand-alone script)

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

# 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"

# Execute TopoToRasterByFile
outTTRByFile = TopoToRasterByFile(inParameterFile)

# Save the output 
outTTRByFile.save("C:/sapyexamples/output/ttrbyfout02")

Environments

Auto Commit, Current Workspace, Default Output Z Value, Extent, Geographic Transformations, Mask, M Resolution, M Tolerance, Maintain Spatial Index, 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, Snap Raster, Tile Size, Transfer Field Domain Descriptions, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance

Licensing information

  • Basic: Requires Spatial Analyst or 3D Analyst
  • Standard: Requires Spatial Analyst or 3D Analyst
  • Advanced: Requires Spatial Analyst or 3D Analyst

Related topics

  • An overview of the Interpolation toolset
  • Find a geoprocessing tool
  • Understanding interpolation analysis
  • Comparing interpolation methods

Feedback on this topic?

In this topic
  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information