Create Terrain

Summary

Creates a new terrain dataset.

Usage

• The Average Point Spacing parameter's 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.

• To complete the terrain, use Add Terrain Pyramid Level to specify the pyramid definition, then Add Feature Class To Terrain to reference the data sources that contribute to the surface, and finally Build Terrain to complete construct the terrain.

• Geoprocessing tools for terrain construction are geared toward data automation procedures in Python scripts and ModelBuilder. Consider using the Terrain Wizard in ArcCatalog or the Catalog window for interactively creating a new terrain. To access the Terrain Wizard, right-click a feature dataset and click New > Terrain.

Syntax

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})

Parameter	Explanation	Data 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, like photogrammetric, lidar, and sonar surveys, typically have a known spacing that should be used. The spacing should be expressed in the horizontal units of the feature dataset's coordinate system.	Double
max_overview_size (Optional)	The terrain overview is akin 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 for optimizing the terrain's storage in an enterprise database.	String
pyramid_type (Optional)	The point thinning method used to construct the terrain pyramids. WINDOWSIZE —Thinning is performed by selecting data points in the area defined by a given window size for each pyramid level using the criterion specified in the windowsize_method parameter. ZTOLERANCE —Thinning is performed by specifying the vertical accuracy of each pyramid level relative to the full resolution of the data points.	String
windowsize_method (Optional)	The criterion used for selecting points in the area defined by the window size. This parameter is only applicable when WINDOWSIZE is specified in the pyramid_type parameter. ZMIN —The point with the smallest elevation value. ZMAX —The point with the largest elevation value. ZMEAN —The point with the elevation value closest to the average of all values. ZMINMAX —The points with the smallest and largest elevation values.	String
secondary_thinning_method (Optional)	Specifies additional thinning options to reduce the number of points used over flat areas when Window Size pyramids are being used. An area is considered flat if the heights of points in an area are within the value supplied for the Secondary Thinning Threshold parameter. Its effect is more evident at higher-resolution pyramid levels, since smaller areas are more likely to be flat than larger areas. NONE —No secondary thinning will be performed. This is the default. MILD —Works best to preserve linear discontinuities (for example, building sides and forest boundaries). It is recommended for lidar that includes both ground and nonground points. It will thin the fewest points. MODERATE —Provides a good trade-off between performance and accuracy. It does not preserve as much detail as mild thinning but comes nearly as close while eliminating more points overall. STRONG —Removes the most points but is less likely to preserve sharply delineated features. Its use should be limited to surfaces where slope tends to change gradually. For example, strong thinning would be efficient for bare-earth lidar and bathymetry.	String
secondary_thinning_threshold (Optional)	The vertical threshold used to activate secondary thinning with the WINDOWSIZE filter. The value should be set equal to or larger than the vertical accuracy of the data.	Double

Derived Output

Name	Explanation	Data 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.

import arcpy
from arcpy import env

arcpy.CheckOutExtension('3D')
env.workspace = 'C:/data'
arcpy.CreateTerrain_3d('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
import exceptions, sys, traceback
from arcpy import env

# 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:
    arcpy.CheckOutExtension("3D")
    # 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:
    # Get the traceback object
    tb = sys.exc_info()[2]
    tbinfo = traceback.format_tb(tb)[0]
    # Concatenate error information into message string
    pymsg = "PYTHON ERRORS:\nTraceback info:\n{0}\nError Info:\n{1}"\
          .format(tbinfo, str(sys.exc_info()[1]))
    msgs = "ArcPy ERRORS:\n {0}\n".format(arcpy.GetMessages(2))
    # Return python error messages for script tool or Python Window
    arcpy.AddError(pymsg)
    arcpy.AddError(msgs)
finally:
    arcpy.CheckInExtension("3D")

Environments

• Current Workspace
• Auto Commit
• Output CONFIG Keyword

Licensing information

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