Add Surface Information (Spatial Analyst)

Summary

Attributes input features with height-based statistical information derived from the overlapping portions of a surface.

Usage

• The statistics from the surface will be determined in the following ways for each supported geometry:

  • For points, z-values will be derived from the x,y coordinates on the surface.
  • For lines, z-properties will be acquired by interpolating surface measurements along their length.
  • For polygons, z-properties of the triangulated surface created from the surface that intersect the polygon will be summarized.

  Curves in input line features will be densified into line segments using the Sampling Distance parameter value. If a sampling distance is not specified, this value will be derived from the input surface. For a raster, the default sampling distance will be the raster's cell size. For a TIN, terrain, or LAS dataset, the default sampling will be based on the edges produced by the triangulated surface. By densifying curves, not all portions of the curve will be accurately captured by the output values. If the curve is shorter than the sampling distance, the curve will be simplified into a two-point line using its start and end points.

• 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 geometry	Surface 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.

• All attributes are calculated based on a TIN surface that is used to interpolate z-information for the input features. Surfaces that are not TIN surfaces are converted into an intermediate TIN dataset. The features are clipped to the boundary of this TIN surface and only the area that is common to both the features and the surface is evaluated. The construction of this TIN may take a considerable amount of time when the input is a dense LAS dataset or a high-resolution raster. If a lower resolution TIN is acceptable for analysis, you can use the Raster To TIN or LAS Dataset To TIN tool to produce a thinned TIN surface for use with this tool.

• The mean z-value for a polygon is calculated by clipping the TIN using the polygon and deriving the results from the clipped TIN. Each triangle in this TIN will have the z-value of its midpoint multiplied by the triangle's 3D area. The results of this calculation for all the triangles are added together and that sum is divided by the cumulative 3D area of those triangles to obtain the final result. When a large polygon feature is specified along with a raster surface that contains a large number of overlapping cells, the process may fail due to insufficient memory resources needed for creating the intermediate TIN surface. If this occurs, you need to create a lower resolution TIN or use a raster-based approach to obtain the expected output properties. Several tools are available in the Zonal Statistics toolset that offer a faster way to derive properties such as area, minimum, maximum, and mean values. The Tabulate Area and Zonal Statistics As Table tools provide an output table that can be joined to the polygon feature. To obtain slope properties, you can create a slope raster and run either of these tools. If you do not have the Spatial Analyst extension but want to compute surface area and volume, you can clip the input raster with the polygon and use the Surface Volume tool, which will output both surface area and volume.

• Line features are processed by draping the lines onto the TIN surface and inserting a vertex where the line crosses a TIN edge. Lines with curved segments are densified into shorter straight segments prior to processing. The mean z-value for a given line is calculated by multiplying the midpoint of the segment by the 3D length of that segment, and adding together the results of this calculation for all the line segments and dividing that sum by the cumulative 3D length of the line 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 unexpected 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. Polygons are internally converted to multipatches (collections of triangles). Each such triangle, when draped onto the surface, is typically split into smaller triangles so that the entire polygon matches the surface throughout. The z-value at the midpoint of each triangle is multiplied by the 3D area of that triangle. The results of this calculation are added together, and that sum is divided by the cumulative 3D area of the triangles, yielding the weighted mean of the z-values at the triangle midpoints.

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	Specifies the surface elevation properties that will be added to the attribute table of the input feature class. Z—The surface z-values interpolated for the x,y-location of each single-point feature will be added. Minimum Z—The 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 Z—The 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 Z—The 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 Area—The 3D surface area for the region defined by each polygon will be added. Surface Length—The 3D distance of the line along the surface will be added. Minimum Slope—The slope value closest to zero along the line or within the area defined by the polygon will be added. Maximum Slope—The highest slope value along the line or within the area defined by the polygon will be added. Average Slope—The 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. Bilinear—An interpolation method exclusive to the raster surface that 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 Neighbors—Elevation 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)	Defines 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 in which line segments with 3D lengths that are shorter than the specified value will be excluded from slope calculations. Polygon features offer an area filter in which polygons covering a surface area smaller than the specified value will be excluded.	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,...]	Specifies the surface elevation properties that will be added to the attribute table of the input feature class. Z—The surface z-values interpolated for the x,y-location of each single-point feature will be added. Z_MIN—The 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_MAX—The 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_MEAN—The 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_AREA—The 3D surface area for the region defined by each polygon will be added. SURFACE_LENGTH—The 3D distance of the line along the surface will be added. MIN_SLOPE—The slope value closest to zero along the line or within the area defined by the polygon will be added. MAX_SLOPE—The highest slope value along the line or within the area defined by the polygon will be added. AVG_SLOPE—The 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. BILINEAR—An interpolation method exclusive to the raster surface that 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_NEIGHBORS—Elevation 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)	Defines 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 in which line segments with 3D lengths that are shorter than the specified value will be excluded from slope calculations. Polygon features offer an area filter in which polygons covering a surface area smaller than the specified value will be excluded.	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