Add Surface Information (Spatial Analyst)

Available with 3D Analyst license.

Available with Spatial Analyst license.

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.

Parameters

Dialog

Label	Explanation	Data 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	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 —Surface Z values interpolated for the XY location of each single-point feature. Minimum Z —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. Maximum Z —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. Mean Z —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. Surface Area —3D surface area for the region defined by each polygon. Surface Length —3D distance of the line along the surface. Minimum Slope —Slope value closest to zero along the line or within the area defined by the polygon. Maximum Slope —Highest slope value along the line or within the area defined by the polygon. Average Slope —Average slope value along the line or within the area defined by the polygon.	String
Method (Optional)	Interpolation method used in determining information about the surface. The available options depend on the data type of the input surface: Bilinear —An interpolation method exclusive to the raster surface which determines cell values from the four nearest cells. This is the only option available for a raster surface. Linear — Default interpolation method for TIN, terrain, and LAS dataset. Obtains elevation from the plane defined by the triangle that contains the XY location of a query point. Natural Neighbors — Obtains elevation by applying area-based weights to the natural neighbors of a query point. Conflate Minimum Z — Obtains elevation from the smallest Z value found among the natural neighbors of a query point. Conflate Maximum Z — Obtains elevation from the largest Z value found among the natural neighbors of a query point. Conflate Nearest Z — Obtains elevation from the nearest value among the natural neighbors of a query point. Conflate Z Closest To Mean — Obtains elevation 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)	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. 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

Derived Output

Label	Explanation	Data Type
Updated Input Features	The updated input features.	Feature Layer

Python

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

Name	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, 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,...]	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 —Surface Z values interpolated for the XY location of each single-point feature. Z_MIN —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. Z_MAX —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. Z_MEAN —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. SURFACE_AREA —3D surface area for the region defined by each polygon. SURFACE_LENGTH —3D distance of the line along the surface. MIN_SLOPE —Slope value closest to zero along the line or within the area defined by the polygon. MAX_SLOPE —Highest slope value along the line or within the area defined by the polygon. AVG_SLOPE —Average slope value along the line or within the area defined by the polygon.	String
method (Optional)	Interpolation method used in determining information about the surface. The available options depend on the data type of the input surface: BILINEAR —An interpolation method exclusive to the raster surface which determines cell values from the four nearest cells. This is the only option available for a raster surface. LINEAR — Default interpolation method for TIN, terrain, and LAS dataset. Obtains elevation from the plane defined by the triangle that contains the XY location of a query point. NATURAL_NEIGHBORS — Obtains elevation by applying area-based weights to the natural neighbors of a query point. CONFLATE_ZMIN — Obtains elevation from the smallest Z value found among the natural neighbors of a query point. CONFLATE_ZMAX — Obtains elevation from the largest Z value found among the natural neighbors of a query point. CONFLATE_NEAREST — Obtains elevation from the nearest value among the natural neighbors of a query point. CONFLATE_CLOSEST_TO_MEAN — Obtains elevation 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)	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. 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

Derived Output

Name	Explanation	Data 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.

from arcpy.sa import *
AddSurfaceInformation("point.shp", "dtm_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_Ex_02.py
# Description: This script demonstrates how to use AddSurfaceInformation 
# on a 2D point feature class in a target workspace.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy.sa import *

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Set the analysis environments
arcpy.env.workspace = "C:/arcpyExamples/data"

# Set the local variables
inFeatureClass = "point.shp"
inSurface = "dtm_tin"
Prop = "Z"
method = "LINEAR"
pyramid = 5

# Execute the tool
AddSurfaceInformation(inFeatureClass, inSurface, Prop, method, 15, 1, pyramid)

Environments

Current Workspace, Extent, Geographic Transformations, Auto Commit

Licensing information

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