Add Surface Information (3D Analyst)
Summary
Attributes features with spatial information derived from a surface.
Usage
Z values from 3D features are ignored. Each feature will summarize surface Z properties that intersect with its geometry. Points derive Z values from the XY location on the surface, lines acquire Z properties by interpolating surface measurements along its length, and polygons summarize the surface Z properties within its area.
-
Output Property options are written to the input feature's attribute table. Each feature defines the location of the surface properties being assessed, and the type of property that can be reported depends on the feature's geometry:
Feature Geometry
Surface Properties
Point
Spot elevation interpolated from the point's XY coordinate on the surface.
Multipoint
Minimum, maximum, and mean spot elevation for all points in the multipoint record.
Polyline
3D distance of the line along the surface.
Minimum, maximum, and mean elevation and slope of the line along the surface.
Polygon
3D area of the surface overlapping the polygon.
Minimum, maximum, and mean of the elevation and slope from the surface.
Slope values are measured in percentage units (grade) and, for line features, get calculated at each segment along the line.
- Minimum slope is obtained from the segment whose value is closest to 0, or horizontal grade.
- Maximum slope is obtained from the segment with the largest calculated value.
- Average slope is obtained by weighing each slope by its 3D length, then determining the average. This results in longer segments having greater influence on the resulting value over shorter segments.
Consider applying a Noise Filter to exclude portions of the surface characterized by anomalous measurements from contributing to slope calculations. Line features are segmented by vertices that capture the profile of the surface, and filtering these segments by length would remove the influence of short segments that are likely caused by undesirable surface measurements. Similarly, the area filter for polygon features excludes sliver triangles in triangulated surfaces from contributing to slope calculations. For raster surfaces, a subset of cell centroids is used to construct a triangulated surface against which the area filter is applied.
Syntax
| Parameter | Explanation | Data Type |
in_feature_class |
The point, multipoint, polyline, or polygon features that define the locations for determining one or more surface properties. | Feature Layer |
in_surface |
The LAS dataset, raster, terrain, or TIN surface used for interpolating z-values. | LAS Dataset Layer; 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:
| String |
method (Optional) |
Interpolation method used in determining surface information. Bilinear interpolation is always used for raster surfaces, whereas the following options are available for triangulated surfaces:
| 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 |
noise_filtering (Optional) |
Excludes portions of the surface that are potentially characterized by anomalous measurements from contributing to slope calculations. Line features offer a length filter, whereas polygons provide an area filter, and the value corresponding with either filtering option is evaluated in the linear units of the feature's coordinate system. Non-slope properties are not affected by this parameter.
| String |
Code Sample
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")
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)