Topo to Raster (Spatial Analyst)

Available with Spatial Analyst license.

Available with 3D Analyst license.

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 z-units. 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 data 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.

  • The Output cell size parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn’t been explicitly specified as the parameter value, it is derived from the Cell Size environment if it has been specified. If the parameter cell size or the environment cell size have not been specified, but the Snap Raster environment has been set, the cell size of the snap raster is used. If nothing is specified, the cell size is calculated from the shorter of the width or height of the extent divided by 250 in which the extent is in the output coordinate system specified in the environment.

  • If the cell size is specified using a numeric value, the tool will use it directly for the output raster.

    If the cell size is specified using a raster dataset, the parameter will show the path of the raster dataset instead of the cell size value. The cell size of that raster dataset will be used directly in the analysis, provided the spatial reference of the dataset is the same as the output spatial reference. If the spatial reference of the dataset is different than the output spatial reference, it will be projected based on the specified Cell Size Projection Method value.

  • 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.

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

  • 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.

  • This tool 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 to produce smaller output rasters. For more details on how to do this, the creating and mosaicking rasters section of the How Topo to Raster works help.

Parameters

LabelExplanationData Type
Input feature data

The input features containing the z-values to be interpolated into a surface raster.

Each feature input can have a field specified that contains the z-values and one of six types specified.

  • Feature layer—The input feature dataset.
  • Field—The name of the field that stores the attributes, where appropriate.
  • Type—The type of input feature dataset.

There are nine types of accepted inputs:

  • Point elevation—A point feature class representing surface elevations. The Field stores the elevations of the points.
  • Contour—A line feature class that represents elevation contours. The Field stores the elevations of the contour lines.
  • Stream—A line feature class of stream locations. All arcs must be oriented to point downstream. The feature class should only contain single arc streams. There is no Field option for this input type.
  • Sink—A point feature class that represents known topographic depressions. The tool will not attempt to remove from the analysis any points explicitly identified as sinks. The Field used should be one that stores the elevation of the legitimate sink. If NONE is selected, only the location of the sink is used.
  • Boundary—A feature class containing a single polygon that represents the outer boundary of the output raster. Cells in the output raster outside this boundary will be NoData. This option can be used for clipping out water areas along coastlines before making the final output raster. There is no Field option for this input type.
  • Lake—A polygon feature class that specifies the location of lakes. All output raster cells within a lake will be assigned to the minimum elevation value of all cells along the shoreline. There is no Field option for this input type.
  • Cliff—A line feature class of the cliffs. The cliff line features must be oriented so that the left-hand side of the line is on the low side of the cliff and the right-hand side is the high side of the cliff. There is no Field option for this input type.
  • Exclusion—A polygon feature class of the areas in which the input data should be ignored. These polygons permit removal of elevation data from the interpolation process. This is typically used to remove elevation data associated with dam walls and bridges. This enables interpolation of the underlying valley with connected drainage structure. There is no Field option for this input type.
  • Coast—A polygon feature class containing the outline of a coastal area. Cells in the final output raster that lie outside these polygons are set to a value that is less than the user-specified minimum height limit. There is no Field option for this input type.
TopoInput
Output cell size
(Optional)

The cell size of the output raster that will be created.

This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.

Analysis Cell Size
Output extent
(Optional)

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 default extent is the largest of all extents of the input feature data.

  • Current Display Extent Map View—The extent will be based on the active map or scene. This option is only available when there is an active map.
  • Draw Extent Draw Extent—The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map.
    Note:

    This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box.

    Note:

    When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent.

  • Extent of a Layer Layer—The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers.

    Each map layer has the following options:

    • All Features Select All—The extent of all features in the layer.
    • Selected Features Area from Selected Features—The extent of the selected features in the layer.
    • Visible Features Extent Indicator—The extent of the visible features in the layer.
      Note:

      The extents from the Selected Features Area from Selected Features and Visible Features Extent Indicator options are only available for feature layers.

  • Browse Browse—The extent will be based on an existing dataset.
  • Clipboard Paste—The extent can be copied to and pasted from the clipboard.
    • Copy Extent Copy—Copies the extent coordinates and coordinate system to the clipboard.
    • Use Paste Extent Paste—Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system.
    Note:

    The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference.

  • Reset Extent Reset—The extent will be reset to the default value.
  • Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system.
    Caution:

    The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.

Extent
Margin in cells
(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 Output extent and Boundary feature datasets 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 In Cells option allows input data beyond these limits to be used in the interpolation.

Long
Smallest z value to be used in interpolation
(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
Largest z value to be used in interpolation
(Optional)

The maximum z-value to be used in the interpolation.

The default is 20 percent above the largest of all input values.

Double
Drainage enforcement
(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.

  • EnforceThe algorithm will attempt to remove all sinks it encounters, whether they are real or spurious. This is the default.
  • Do not enforceNo sinks will be filled.
  • Enforce with sinkPoints identified as sinks in Input feature data represent known topographic depressions and will not be altered. Any sink not identified in input feature data is considered spurious, and the algorithm will attempt to fill it.Having more than 8,000 spurious sinks causes the tool to fail.
String
Primary type of input data
(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.

  • ContourThe dominant type of input data will be elevation contours. This is the default.
  • SpotThe dominant type of input will be point.
String
Maximum number of 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
Discretisation 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
Output stream polyline 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:

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)

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
Output 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
Output 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 curvature roughness 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
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

TopoToRaster(in_topo_features, {cell_size}, {extent}, {Margin}, {minimum_z_value}, {maximum_z_value}, {enforce}, {data_type}, {maximum_iterations}, {roughness_penalty}, {discrete_error_factor}, {vertical_standard_error}, {tolerance_1}, {tolerance_2}, {out_stream_features}, {out_sink_features}, {out_diagnostic_file}, {out_parameter_file}, {profile_penalty}, {out_residual_feature}, {out_stream_cliff_error_feature}, {out_contour_error_feature})
NameExplanationData Type
in_topo_features
topo_input
TopoInput
cell_size
(Optional)

The cell size of the output raster that will be created.

This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.

Analysis Cell Size
extent
(Optional)

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 default extent is the largest of all extents of the input feature data.

  • MAXOF—The maximum extent of all inputs will be used.
  • MINOF—The minimum area common to all inputs will be used.
  • DISPLAY—The extent is equal to the visible display.
  • Layer name—The extent of the specified layer will be used.
  • Extent object—The extent of the specified object will be used.
  • Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max.
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.

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.

  • ENFORCEThe algorithm will attempt to remove all sinks it encounters, whether they are real or spurious. This is the default.
  • NO_ENFORCENo sinks will be filled.
  • ENFORCE_WITH_SINKPoints identified as sinks in Input feature data represent known topographic depressions and will not be altered. Any sink not identified in input feature data is considered spurious, and the algorithm will attempt to fill it.Having more than 8,000 spurious sinks causes the tool to fail.
String
data_type
(Optional)

The dominant elevation data type of the input feature data.

  • CONTOURThe dominant type of input data will be elevation contours. This is the default.
  • SPOTThe dominant type of input will be point.

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:

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)

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:

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

Related topics