Add Surface Information (3D Analyst)

License Level:BasicStandardAdvanced

Summary

Attributes features with spatial information derived from a surface.

Usage

Syntax

AddSurfaceInformation_3d (in_feature_class, in_surface, out_property, {method}, {sample_distance}, {z_factor}, {pyramid_level_resolution}, {noise_filtering})
ParameterExplanationData 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:

  • ZSurface elevation interpolated for the XY location of each single-point feature.
  • Z_MINLowest surface elevation in the area defined by the polygon, along the length of a line, or among the interpolated values for points in a multipoint record.
  • Z_MAXHighest surface elevation in the area defined by the polygon, along the length of a line, or among the interpolated values for points in a multipoint record.
  • Z_MEANAverage surface elevation of the area defined by the polygon, along the length of a line, or among the interpolated values for points in a multipoint record.
  • SURFACE_AREA3D surface area for the region defined by each polygon.
  • SURFACE_LENGTH3D distance of the line along the surface.
  • MIN_SLOPESlope value closest to zero along the line or within the area defined by the polygon.
  • MAX_SLOPEHighest slope value along the line or within the area defined by the polygon.
  • AVG_SLOPEAverage slope value along the line or within the area defined by the polygon.
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:

  • LINEAR Z value is interpolated from the plane of the surface triangle containing the query point. This is the default.
  • NATURAL_NEIGHBORS Applies area-based weights to surface measurements in the natural neighborhood of a query point.
  • CONFLATE_ZMIN Uses smallest Z value from surface measurements in the natural neighborhood of a query point.
  • CONFLATE_ZMAX Uses largest Z value from surface measurements in the natural neighborhood of a query point.
  • CONFLATE_NEAREST Obtains Z value from surface measurement whose XY distance is nearest to the query point.
  • CONFLATE_CLOSEST_TO_MEAN Obtains Z value from the surface measurement in the natural neighborhood of the query point whose value is closest to the average of neighboring measurements.
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.

  • NO_FILTERNo noise filter will be used to limit the line segments or surface triangles factored into the slope calculations. This is the default.
  • AREA <value>Surface triangles with 3D areas less than the specified value will be excluded from contributing to slope calculations.
  • LENGTH <value> Line segments whose 3D length after being interpolated on the surface is shorter than the specified value will be excluded from contributing to slope calculations.
String

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

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
11/8/2012