Summary
Calculate the displacement between two surfaces to determine where one is above, below or the same as the other surface.
Usage
The output will only represent the overlapping portions of the input surfaces.
Consider generating an output raster or TIN to evaluate the Z difference between the input and reference surface.
It's best if the horizontal and vertical coordinate systems of the input surfaces are the same.
The output feature class will have polygon features that will separate regions of the input surface by whether they are above, below, or the same as the reference plane. The feature's attribute table will have the following fields:
- Volume—The volume of space between the input and reference surface that is bounded by the polygon. Volume will always be 0 for areas where the two surfaces are the same.
- SArea—The surface area of the input surface that is bounded by the polygon.
- Code—A numeric value that describes the spatial relationship of the surface to the reference plane. -1 indicates the surface is below the reference plane, 0 indicates the surface is the same as the reference plane, and 1 indicates the surface is above the reference plane.
Syntax
SurfaceDifference(in_surface, in_reference_surface, out_feature_class, {pyramid_level_resolution}, {reference_pyramid_level_resolution}, {out_raster}, {raster_cell_size}, {out_tin_folder}, {out_tin_basename}, method, reference_method, {extent}, boundary)| Parameter | Explanation | Data Type |
in_surface | The triangulated surface whose relative displacement is being evaluated from the reference surface. | LAS Dataset Layer; Terrain Layer; TIN Layer |
in_reference_surface | The triangulated surface that will be used as the baseline for determining the relative displacement of the input surface. | LAS Dataset Layer; Terrain Layer; TIN Layer |
out_feature_class | The output feature class containing contiguous triangles and triangle parts that have the same classification grouped into polygons. The volume enclosed by each region of difference is listed in the attribute table. | Feature Class |
pyramid_level_resolution (Optional) | The resolution that will be used to generate the input surface. For a terrain dataset, this will correspond to its pyramid-level definitions, where the default of 0 represents full resolution. For a LAS dataset, this value represents the length of each side of the square area that will be used to thin the LAS point returns. | Double |
reference_pyramid_level_resolution (Optional) | The resolution that will be used to generate the reference surface. For a terrain dataset, this will correspond to its pyramid-level definitions, where the default of 0 represents full resolution. For a LAS dataset, this value represents the length of each side of the square area that will be used to thin the LAS points returns. | Double |
out_raster (Optional) | The output raster surface whose values represent the input surface normalized against the reference surface. Positive values reflect areas where the input surface is above the reference surface, whereas negative values indicate the areas where the input surface is below the reference surface. The raster's values are derived from a TIN using linear interpolation. | Raster Dataset |
raster_cell_size (Optional) | The cell size of the output raster. | Double |
out_tin_folder (Optional) | The folder location for storing one or more TIN surfaces whose values represent the difference between the input and reference surface. | Folder |
out_tin_basename (Optional) | The base name given to each output TIN surface. If one TIN dataset is not sufficient to represent the data, multiple TINs will be created with the same base name. | String |
method | The method used to select a LAS point in each analysis window when applying an analysis resolution to thin the input LAS dataset surface. The resulting points will be used to construct a triangulated surface.
| String |
reference_method | The method used to select a LAS point in each analysis window when applying an analysis resolution to thin the input LAS dataset surface. The resulting points will be used to construct a triangulated surface.
| String |
extent (Optional) | Specifies the extent of the data that will be evaluated by this tool. | Extent |
boundary | A polygon feature that defines the area of interest to be processed by this tool. | Feature Layer |
Code sample
SurfaceDifference 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.SurfaceDifference_3d("sample.gdb/featuredataset/terrain", "sample.gdb/featuredataset/terrain2", "surface_diff.shp")
SurfaceDifference example 2 (stand-alone script)
The following sample demonstrates the use of this tool in a stand-alone Python script.
'''****************************************************************************
Name: SurfaceDifference Example
Description: This script demonstrates how to use the
SurfaceDifference tool.
****************************************************************************'''
# Import system modules
import arcpy
from arcpy import env
# Obtain a license for the ArcGIS 3D Analyst extension
arcpy.CheckOutExtension("3D")
# Set environment settings
env.workspace = "C:/data"
# Set Local Variables
inSurface = "flood_tin"
inReference = "elev_tin"
# Ensure output name is unique
outPoly = arcpy.CreateUniqueName("difference.shp")
#Execute SurfaceDifference
arcpy.SurfaceDifference_3d(inSurface, inReference, outPoly)
del arcpy, inSurface, inReference, outPoly
Environments
Licensing information
- Basic: Requires 3D Analyst
- Standard: Requires 3D Analyst
- Advanced: Requires 3D Analyst