Create Terrain (3D Analyst)

License Level:BasicStandardAdvanced

Summary

Creates a new terrain dataset.

Usage

Syntax

CreateTerrain_3d (in_feature_dataset, out_terrain_name, average_point_spacing, {max_overview_size}, {config_keyword}, {pyramid_type}, {windowsize_method}, {secondary_thinning_method}, {secondary_thinning_threshold})
ParameterExplanationData Type
in_feature_dataset

The feature dataset where the terrain dataset will be created.

Feature Dataset
out_terrain_name

The output terrain dataset.

String
average_point_spacing

The average, or nominal, horizontal distance between points for the data being used to build the terrain. Data collected for photogrammetric, lidar, and sonar surveys typically have a known spacing. This is the value that should be used. If you're unsure of the spacing you should go back and check the data rather than guess. The spacing is given in the horizontal units of the feature dataset's coordinate system.

Double
max_overview_size
(Optional)

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

Long
config_keyword
(Optional)

Configuration keyword for ArcSDE. A configuration keyword is used to optimize database storage and is typically configured by the database administrator.

String
pyramid_type
(Optional)

The point thinning method used to construct the terrain pyramids.

  • WINDOWSIZEThinning 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 Window Size Method parameter.
  • ZTOLERANCEThinning 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.

  • ZMINThe point with the smallest elevation value.
  • ZMAXThe point with the largest elevation value.
  • ZMEANThe point with the elevation value closest to the average of all values.
  • ZMINMAXThe 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.

  • NONENo secondary thinning will be performed. This is the default.
  • MILDWorks 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.
  • MODERATEProvides 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.
  • STRONGRemoves 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 Window Size filter. The value should be set equal to or larger than the vertical accuracy of the data.

Double

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

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Requires 3D Analyst
ArcGIS for Desktop Standard: Requires 3D Analyst
ArcGIS for Desktop Advanced: Requires 3D Analyst
3/7/2014