Create Terrain (3D Analyst)

Summary

Creates a terrain dataset.

Usage

  • The Average Point Spacing parameter value should reflect a sound approximation of the data that will be used in the terrain, as it will be used to define the size of the terrain's internal tiles, which are used to optimize data analysis and display performance. Each tile is approximated to contain no more than 200,000 source elevation points. If the data has been gathered at significantly different densities from one location to another, the specified value should favor the smaller spacing.

  • After executing this tool, use Add Terrain Pyramid Level to specify the pyramid definition, Add Feature Class To Terrain to reference the data sources that contribute to the surface, and Build Terrain (in that order) to complete construction of the terrain.

Parameters

LabelExplanationData Type
Input Feature Dataset

The feature dataset that will contain the terrain dataset.

Feature Dataset
Output Terrain

The name of the terrain dataset.

String
Average Point Spacing

The average horizontal distance between the data points that will be used in modeling the terrain. Sensor based measurements—such as photogrammetric, lidar, and sonar surveys—typically have a known spacing that should be used. Use the horizontal units of the feature dataset's coordinate system for the spacing.

Double
Maximum Overview Size
(Optional)

The terrain overview is similar to the image thumbnail concept. It is the coarsest representation of the terrain dataset, and the maximum size represents the upper limit of the number of measurement points that can be sampled to create the overview.

Long
Config Keyword
(Optional)

The configuration keyword that will be used to optimize the terrain's storage in an enterprise database.

String
Pyramid Type
(Optional)

Specifies the point thinning method that will be used to construct the terrain pyramids.

  • Window SizeData points in the area defined by a given window size for each pyramid level will be selected using the Window Size Method parameter value. This is the default.
  • Z ToleranceThe vertical accuracy of each pyramid level relative to the full resolution of the data points will be specified.
String
Window Size Method
(Optional)

Specifies how points in the area defined by the window size will be selected. This parameter is only applicable when Window Size is specified for the Pyramid Type parameter.

  • Minimum ZThe point with the smallest elevation value will be selected. This is the default.
  • Maximum ZThe point with the largest elevation value will be selected.
  • Closest To Mean ZThe point with the elevation value closest to the average of all values will be selected.
  • Minimum and Maximum ZThe points with the smallest and largest elevation values will be selected.
String
Secondary Thinning Method
(Optional)

Specifies additional thinning that will be performed to reduce the number of points used over flat areas when window size pyramids are used. An area is considered flat if the heights of points in that area are within the Secondary Thinning Threshold parameter value. Its effect is more evident at higher-resolution pyramid levels, since smaller areas are more likely to be flat than larger areas.

  • NoneNo secondary thinning will be performed. This is the default.
  • MildMild thinning will be performed to preserve linear discontinuities (for example, building sides and forest boundaries). This method is recommended for lidar that includes both ground and nonground points. It will thin the fewest points.
  • ModerateModerate thinning will be performed, which provides a balance between performance and accuracy. This method does not preserve as much detail as mild thinning but comes close while eliminating more points overall.
  • StrongStrong thinning will be performed, which removes the most points but is less likely to preserve sharply delineated features. Limit its use to surfaces where slope tends to change gradually. For example, strong thinning is efficient for bare-earth lidar and bathymetry.
String
Secondary Thinning Threshold
(Optional)

The vertical threshold that will be used to activate secondary thinning when the Pyramid Type parameter is set to Window Size. Set the value equal to or larger than the vertical accuracy of the data.

Double
Triangulation Method
(Optional)

Specifies whether breakline features will be incorporated into the terrain surface by densifying their segments to conform to Delaunay triangulation rules for constructing a TIN surface.

Delaunay triangulation will densify breakline features to accommodate the points surrounding them in a manner that avoids the creation of long, thin triangles that typically yield undesirable results when analyzing a TIN-based surface. Additionally, natural neighbor interpolation and Thiessen (Voronoi) polygon generation can only be performed on conforming Delaunay triangulations.

A constrained Delaunay triangulation will avoid densifying breakline features, incorporating breakline segments as edges into the TIN surface. Consider this option when you need to explicitly define certain edges that are guaranteed not to be modified (that is, split into multiple edges) by the triangulator.

  • DelaunayBreaklines will be densified to construct Delaunay triangles that accommodate the points surrounding them. This is the default.
  • Constrained DelaunayBreaklines will not be densified.
String

Derived Output

LabelExplanationData Type
Output Terrain

The new terrain dataset.

Terrain

arcpy.ddd.CreateTerrain(in_feature_dataset, out_terrain_name, average_point_spacing, {max_overview_size}, {config_keyword}, {pyramid_type}, {windowsize_method}, {secondary_thinning_method}, {secondary_thinning_threshold}, {triangulation_method})
NameExplanationData Type
in_feature_dataset

The feature dataset that will contain the terrain dataset.

Feature Dataset
out_terrain_name

The name of the terrain dataset.

String
average_point_spacing

The average horizontal distance between the data points that will be used in modeling the terrain. Sensor based measurements—such as photogrammetric, lidar, and sonar surveys—typically have a known spacing that should be used. Use the horizontal units of the feature dataset's coordinate system for the spacing.

Double
max_overview_size
(Optional)

The terrain overview is similar to the image thumbnail concept. It is the coarsest representation of the terrain dataset, and the maximum size represents the upper limit of the number of measurement points that can be sampled to create the overview.

Long
config_keyword
(Optional)

The configuration keyword that will be used to optimize the terrain's storage in an enterprise database.

String
pyramid_type
(Optional)

Specifies the point thinning method that will be used to construct the terrain pyramids.

  • WINDOWSIZEData points in the area defined by a given window size for each pyramid level will be selected using the windowsize_method parameter value. This is the default.
  • ZTOLERANCEThe vertical accuracy of each pyramid level relative to the full resolution of the data points will be specified.
String
windowsize_method
(Optional)

Specifies how points in the area defined by the window size will be selected. This parameter is only applicable when WINDOWSIZE is specified for the pyramid_type parameter.

  • ZMINThe point with the smallest elevation value will be selected. This is the default.
  • ZMAXThe point with the largest elevation value will be selected.
  • ZMEANThe point with the elevation value closest to the average of all values will be selected.
  • ZMINMAXThe points with the smallest and largest elevation values will be selected.
String
secondary_thinning_method
(Optional)

Specifies additional thinning that will be performed to reduce the number of points used over flat areas when window size pyramids are used. An area is considered flat if the heights of points in that area are within the secondary_thinning_threshold parameter value. Its effect is more evident at higher-resolution pyramid levels, since smaller areas are more likely to be flat than larger areas.

  • NONENo secondary thinning will be performed. This is the default.
  • MILDMild thinning will be performed to preserve linear discontinuities (for example, building sides and forest boundaries). This method is recommended for lidar that includes both ground and nonground points. It will thin the fewest points.
  • MODERATEModerate thinning will be performed, which provides a balance between performance and accuracy. This method does not preserve as much detail as mild thinning but comes close while eliminating more points overall.
  • STRONGStrong thinning will be performed, which removes the most points but is less likely to preserve sharply delineated features. Limit its use to surfaces where slope tends to change gradually. For example, strong thinning is efficient for bare-earth lidar and bathymetry.
String
secondary_thinning_threshold
(Optional)

The vertical threshold that will be used to activate secondary thinning when the pyramid_type parameter is set to WINDOWSIZE. Set the value equal to or larger than the vertical accuracy of the data.

Double
triangulation_method
(Optional)

Specifies whether breakline features will be incorporated into the terrain surface by densifying their segments to conform to Delaunay triangulation rules for constructing a TIN surface.

Delaunay triangulation will densify breakline features to accommodate the points surrounding them in a manner that avoids the creation of long, thin triangles that typically yield undesirable results when analyzing a TIN-based surface. Additionally, natural neighbor interpolation and Thiessen (Voronoi) polygon generation can only be performed on conforming Delaunay triangulations.

A constrained Delaunay triangulation will avoid densifying breakline features, incorporating breakline segments as edges into the TIN surface. Consider this option when you need to explicitly define certain edges that are guaranteed not to be modified (that is, split into multiple edges) by the triangulator.

  • DELAUNAYBreaklines will be densified to construct Delaunay triangles that accommodate the points surrounding them. This is the default.
  • CONSTRAINED_DELAUNAYBreaklines will not be densified.
String

Derived Output

NameExplanationData Type
derived_out_terrain

The new terrain dataset.

Terrain

Code sample

CreateTerrain example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

arcpy.env.workspace = 'C:/data'
arcpy.ddd.CreateTerrain('source.gdb/Redlands', 'Redlands_terrain',  5,
                      50000, '', 'WINDOWSIZE', 'ZMIN', 'NONE', 1)
CreateTerrain example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

"""****************************************************************************
Name: Create Terrain from TIN
Description: This script demonstrates how to create a terrain dataset using
             features extracted from a TIN. It is particularly useful in
             situations where the source data used in the TIN is not available,
             and the amount of data stored in the TIN proves to be too large
             for the TIN. The terrain's scalability will allow improved
             display performance and faster analysis. The script is designed
             to work as a script tool with 5 input arguments.
****************************************************************************"""
# Import system modules
import arcpy

# Set local variables
tin = arcpy.GetParameterAsText(0) # TIN used to create terrain
gdbLocation = arcpy.GetParameterAsText(1) # Folder that will store terran GDB
gdbName = arcpy.GetParameterAsText(2) # Name of terrain GDB
fdName = arcpy.GetParameterAsText(3) # Name of feature dataset
terrainName = arcpy.GetParameterAsText(4) # Name of terrain

try:
    # Create the file gdb that will store the feature dataset
    arcpy.management.CreateFileGDB(gdbLocation, gdbName)
    gdb = '{0}/{1}'.format(gdbLocation, gdbName)
    # Obtain spatial reference from TIN
    SR = arcpy.Describe(tin).spatialReference
    # Create the feature dataset that will store the terrain
    arcpy.management.CreateFeatureDataset(gdb, fdName, SR)
    fd = '{0}/{1}'.format(gdb, fdName)
    # Export TIN elements to feature classes for terrain
    arcpy.AddMessage("Exporting TIN footprint to define terrain boundary...")
    boundary = "{0}/boundary".format(fd)
    # Execute TinDomain
    arcpy.ddd.TinDomain(tin, tinDomain, 'POLYGON')
    arcpy.AddMessage("Exporting TIN breaklines...")
    breaklines = "{0}/breaklines".format(fd)
    # Execute TinLine
    arcpy.ddd.TinLine(tin, breaklines, "Code")
    arcpy.AddMessage("Exporting TIN nodes...")
    masspoints = "{0}/masspoints".format(fd)
    # Execute TinNode
    arcpy.ddd.TinNode(sourceTIN, TIN_nodes)
    arcpy.AddMessage("Creating terrain dataset...")
    terrain = "terrain_from_tin"
    # Execute CreateTerrain
    arcpy.ddd.CreateTerrain(fd, terrainName, 10, 50000, "",
                            "WINDOWSIZE", "ZMEAN", "NONE", 1)
    arcpy.AddMessage("Adding terrain pyramid levels...")
    terrain = "{0}/{1}".format(fd, terrainName)
    pyramids = ["20 5000", "25 10000", "35 25000", "50 50000"]
    # Execute AddTerrainPyramidLevel
    arcpy.ddd.AddTerrainPyramidLevel(terrain, "", pyramids)
    arcpy.AddMessage("Adding features to terrain...")
    inFeatures = "{0} Shape softclip 1 0 10 true false boundary_embed <None> "\
             "false; {1} Shape masspoints 1 0 50 true false points_embed "\
             "<None> false; {2} Shape softline 1 0 25 false false lines_embed "\
             "<None> false".format(boundary, masspoints, breaklines)
    # Execute AddFeatureClassToTerrain
    arcpy.ddd.AddFeatureClassToTerrain(terrain, inFeatures)
    arcpy.AddMessage("Building terrain...")
    # Execute BuildTerrain
    arcpy.ddd.BuildTerrain(terrain, "NO_UPDATE_EXTENT")
    arcpy.GetMessages()

except arcpy.ExecuteError:
    print(arcpy.GetMessages())
except Exception as err:
    print(err)

Related topics