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 if you wish 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_3d (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})| Parameter | Explanation | Data Type |
in_surface | The terrain or TIN surface whose relative displacement is being evaluated from the reference surface. | Terrain Layer; TIN Layer |
in_reference_surface | The terrain or TIN surface that will be used as the baseline for determining the relative displacement of the input surface. | 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 terrain pyramid-level that will be used to generate the input surface. The default is 0, or full resolution. This parameter is only used with the terrain dataset. | Double |
reference_pyramid_level_resolution (Optional) | The terrain pyramid-level that will be used to generate the reference surface. The default is 0, or full resolution. This parameter is only used with the terrain dataset. | 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 the 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 |
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
- ArcGIS for Desktop Basic: Requires 3D Analyst
- ArcGIS for Desktop Standard: Requires 3D Analyst
- ArcGIS for Desktop Advanced: Requires 3D Analyst