Add Surface Information (3D Analyst)

Summary

Interpolates surface elevation properties for point, multipoint, and polyline features.

Usage

• Z values from 3D feature classes are ignored. All features are treated as 2-dimensional features.

• Output Property options get written to the attribute table of the input feature class and are dependant on the feature's geometry. The following list summarizes the options available for each supported geometry type:

  • Point—z
  • Multipoint—z minimum, z maximum, z mean
  • Polyline—z minimum, z maximum, z mean, surface length, minimum slope, maximum slope, average slope

• Slope values for line features are calculated as a percent, or grade, for each line segment.

  • Min slope is obtained from the segment whose value is closest to 0, or horizontal grade.
  • Max slope is obtained from the segment with the largest calculated value.
  • Average slope is obtained by averaging the slope of all line segments after weighing each segment by its 3D length. This results in longer segments having greater influence on the resulting value over shorter segments.

Syntax

AddSurfaceInformation_3d (in_feature_class, in_surface, out_property, {method}, {sample_distance}, {z_factor}, {pyramid_level_resolution})

Parameter	Explanation	Data Type
in_feature_class	The input point, multipoint, or polyline feature class.	Feature Layer
in_surface	The raster, TIN, or terrain surface used for interpolating z-values.	Raster Layer; Terrain Layer; TIN Layer
out_property	The surface elevation property that will be added to the attribute table of the input feature class. The following list summarizes the available property keywords and their supported geometry types: Z —The interpolated elevation value for single-point features. Z_MIN —The lowest interpolated elevation value for multipoint and polyline features. Z_MAX —The highest interpolated elevation value for multipoint and polyline features. Z_MEAN —The average interpolated elevation value for multipoint and polyline features. SURFACE_LENGTH —The length of the polyline feature when draped along the input surface. MIN_SLOPE —The lowest interpolated slope value for polyline features. MAX_SLOPE —The highest interpolated slope value for polyline features. AVG_SLOPE —The average interpolated slope value for polyline features.	String
method (Optional)	Interpolation method to be used in determining Z values for input features. Available options are: LINEAR — Default interpolation method. Estimates z from the plane defined by the TIN or terrain triangle that contains the XY location of a query point. NATURAL_NEIGHBORS — Estimates z by applying area-based weights to the TIN or terrain's natural neighbors of a query point. CONFLATE_ZMIN — Obtains z from one of the TIN or terrain's natural neighbors of a query point. The z of the neighbor with the minimum height is used. CONFLATE_ZMAX — Obtains z from one of the TIN or terrain's natural neighbors of a query point. The z of the neighbor with the maximum height is used. CONFLATE_NEAREST — Obtains z from one of the TIN or terrain's natural neighbors of a query point. The z of the neighbor closest in XY to the query point is used. CONFLATE_CLOSEST_TO_MEAN — Obtains z from one of the TIN or terrain's natural neighbors of a query point. The z of the neighbor which is closest to the average height of all the neighbors is used.	String
sample_distance (Optional)	The spacing at which z-values will be interpolated. By default, the raster cell size is used when the input surface is a raster, and the natural densification of the triangulated surface is used when the input is a terrain or TIN dataset.	Double
z_factor (Optional)	The factor by which elevation values will be multiplied. This is typically used to convert Z linear units that match those of the XY linear units. The default is 1, which leaves elevation values unchanged.	Double
pyramid_level_resolution (Optional)	The z-tolerance or window-size resolution of the terrain pyramid level that will be used by this tool. The default is 0, or full resolution.	Double

Code Sample

AddSurfaceInformation 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.AddSurfaceInformation_3d("points.shp", "my_tin", "Z", "LINEAR")

AddSurfaceInformation example 2 (stand-alone script)

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

'''*********************************************************************
Name: AddSurfaceInformation Example
Description: This script demonstrates how to use AddSurfaceInformation 
             on all 2D feature classes in a target workspace.
*********************************************************************'''
# Import system modules
import arcpy
from arcpy import env
import exceptions, sys, traceback

try:
    arcpy.CheckOutExtension("3D")
    # Set Local Variables
    env.workspace = 'c:/data'
    inSurface = 'fgdb.gdb/municipal/terrain'
    pyramid = 5
    method = "BILINEAR"
    # Create list of feature classes
    fcList = arcpy.ListFeatureClasses()
    if fcList:
        for fc in fcList:
            desc = arcpy.Describe(fc)
            # Determine if the feature is 2D
            if not desc.hasZ:
                if desc.shapeType == "Polygon":
                    # Desired properties separated by semi-colons
                    Prop = "Z_MIN;Z_MAX" 
                elif desc.shapeType == "Point":
                    Prop = "Z"
                elif desc.shapeType == "Multipoint":
                    Prop = "Z_MIN;Z_MAX;Z_MEAN"
                elif desc.shapeType == "Polyline":
                    Prop = "LENGTH_3D"
                # Execute AddSurfaceInformation
                arcpy.ddd.AddSurfaceInformation(fc, inSurface, Prop, 
                                                method, 15, 1, pyramid)
                print "Completed adding surface information."
    arcpy.CheckInExtension('3D')

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)

Environments

Current Workspace, Scratch Workspace, Extent, Geographic Transformations, Auto Commit

Licensing Information

ArcView: Requires 3D Analyst

ArcEditor: Requires 3D Analyst

ArcInfo: Requires 3D Analyst