Add Surface Information (3D Analyst)

Summary

Attributes features with spatial information derived from a surface.

Usage

  • The z-values from 3D features are ignored. Each feature will summarize surface z-properties that intersect its geometry. Points derive z-values from the x,y-location on the surface, lines acquire z-properties by interpolating surface measurements along their length, and polygons summarize the surface z-properties within their area.

  • The Output Property parameter 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 geometrySurface properties

    Point

    Spot elevation interpolated from the point's x,y-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, are calculated at each segment along the line.

    • Minimum slope is obtained from the segment with the value closest to 0, or horizontal grade.
    • Maximum slope is obtained from the segment with the largest calculated value.
    • Average slope for a polyline is obtained by taking a weighted average of the slope from each line segment. The weighting is based on the 3D length of each segment. This results in longer segments having greater influence on the resulting calculation over shorter segments.
  • Use the Noise Filter parameter 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 removes 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 to which the area filter is applied.

Parameters

LabelExplanationData Type
Input Features

The point, multipoint, polyline, or polygon features that define the locations for determining one or more surface properties.

Feature Layer
Input Surface

The LAS dataset, mosaic, raster, terrain, or TIN surface used for interpolating z-values.

LAS Dataset Layer; Mosaic Layer; Raster Layer; Terrain Layer; TIN Layer
Output Property

Specifies the surface elevation property that will be added to the attribute table of the input feature class.

  • ZThe surface z-values interpolated for the x,y-location of each single-point feature will be added.
  • Minimum ZThe lowest surface z-values in the area defined by the polygon, along the length of a line, or among the interpolated values for points in a multipoint record will be added.
  • Maximum ZThe highest 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 will be added.
  • Mean ZThe average 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 will be added.
  • Surface AreaThe 3D surface area for the region defined by each polygon will be added.
  • Surface LengthThe 3D distance of the line along the surface will be added.
  • Minimum SlopeThe slope value closest to zero along the line or within the area defined by the polygon will be added.
  • Maximum SlopeThe highest slope value along the line or within the area defined by the polygon will be added.
  • Average SlopeThe average slope value along the line or within the area defined by the polygon will be added.
String
Method
(Optional)

Specifies the interpolation method that will be used to determine information about the surface.

  • BilinearAn interpolation method exclusive to the raster surface which determines cell values from the four nearest cells will be used. This is the only option available for a raster surface.
  • Linear Elevation will be obtained from the plane defined by the triangle that contains the x,y-location of a query point. This is the default interpolation method for TINs, terrains, and LAS datasets.
  • Natural NeighborsElevation will be obtained by applying area-based weights to the natural neighbors of a query point.
  • Conflate Minimum Z Elevation will be obtained from the smallest z-value found among the natural neighbors of a query point.
  • Conflate Maximum Z Elevation will be obtained from the largest z-value found among the natural neighbors of a query point.
  • Conflate Nearest Z Elevation will be obtained from the nearest value among the natural neighbors of a query point.
  • Conflate Z Closest To Mean Elevation will be obtained from the z-value that is closest to the average of all the natural neighbors of a query point.
String
Sampling 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 z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z datum with a specified linear unit.

Double
Pyramid Level Resolution
(Optional)

The z-tolerance or window-size resolution of the terrain pyramid level that will be used. The default is 0, or full resolution.

Double
Noise Filtering
(Optional)

Specifies whether portions of the surface that are potentially characterized by anomalous measurements will be excluded from contributing to slope calculations. Other properties are not affected by this parameter.

Line features offer a length filter, wherein line segments whose 3D lengths are shorter than the specified value are excluded from slope calculations. Polygon features offer an area filter, wherein polygons covering a surface area smaller than the specified value are excluded.

String

Derived Output

LabelExplanationData Type
Updated Input Features

The updated input features.

Feature Layer

arcpy.ddd.AddSurfaceInformation(in_feature_class, in_surface, out_property, {method}, {sample_distance}, {z_factor}, {pyramid_level_resolution}, {noise_filtering})
NameExplanationData 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, mosaic, raster, terrain, or TIN surface used for interpolating z-values.

LAS Dataset Layer; Mosaic Layer; Raster Layer; Terrain Layer; TIN Layer
out_property
[out_property,...]

Specifies the surface elevation property that will be added to the attribute table of the input feature class.

  • ZThe surface z-values interpolated for the x,y-location of each single-point feature will be added.
  • Z_MINThe lowest surface z-values in the area defined by the polygon, along the length of a line, or among the interpolated values for points in a multipoint record will be added.
  • Z_MAXThe highest 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 will be added.
  • Z_MEANThe average 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 will be added.
  • SURFACE_AREAThe 3D surface area for the region defined by each polygon will be added.
  • SURFACE_LENGTHThe 3D distance of the line along the surface will be added.
  • MIN_SLOPEThe slope value closest to zero along the line or within the area defined by the polygon will be added.
  • MAX_SLOPEThe highest slope value along the line or within the area defined by the polygon will be added.
  • AVG_SLOPEThe average slope value along the line or within the area defined by the polygon will be added.
String
method
(Optional)

Specifies the interpolation method that will be used to determine information about the surface.

  • BILINEARAn interpolation method exclusive to the raster surface which determines cell values from the four nearest cells will be used. This is the only option available for a raster surface.
  • LINEAR Elevation will be obtained from the plane defined by the triangle that contains the x,y-location of a query point. This is the default interpolation method for TINs, terrains, and LAS datasets.
  • NATURAL_NEIGHBORSElevation will be obtained by applying area-based weights to the natural neighbors of a query point.
  • CONFLATE_ZMIN Elevation will be obtained from the smallest z-value found among the natural neighbors of a query point.
  • CONFLATE_ZMAX Elevation will be obtained from the largest z-value found among the natural neighbors of a query point.
  • CONFLATE_NEAREST Elevation will be obtained from the nearest value among the natural neighbors of a query point.
  • CONFLATE_CLOSEST_TO_MEAN Elevation will be obtained from the z-value that is closest to the average of all the natural neighbors of a query point.
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 z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z datum with a specified linear unit.

Double
pyramid_level_resolution
(Optional)

The z-tolerance or window-size resolution of the terrain pyramid level that will be used. The default is 0, or full resolution.

Double
noise_filtering
(Optional)

Specifies whether portions of the surface that are potentially characterized by anomalous measurements will be excluded from contributing to slope calculations. Other properties are not affected by this parameter.

Line features offer a length filter, wherein line segments whose 3D lengths are shorter than the specified value are excluded from slope calculations. Polygon features offer an area filter, wherein polygons covering a surface area smaller than the specified value are excluded.

String

Derived Output

NameExplanationData Type
output_feature_class

The updated input features.

Feature Layer

Code sample

AddSurfaceInformation example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

arcpy.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

# Set Local Variables
arcpy.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.")

Licensing information

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

Related topics