Surface Difference (3D Analyst)

Summary

Calculate the displacement between two surfaces to determine where one is above, below or the same as the other surface.

Learn more about how Surface Difference works

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

arcpy.3d.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)
ParameterExplanationData 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.

  • CLOSEST_TO_MEANThe LAS point whose value is closest to the mean of all LAS points in the analysis window will be used. This is the default.
  • MINThe LAS point with the smallest z-value among all the LAS points in the analysis window.
  • MAXThe LAS point with the highest z-value among all the LAS points in the analysis window.
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.

  • CLOSEST_TO_MEANThe LAS point whose value is closest to the mean of all LAS points in the analysis window will be used. This is the default.
  • MINThe LAS point with the smallest z-value among all the LAS points in the analysis window.
  • MAXThe LAS point with the highest z-value among all the LAS points in the analysis window.
String
extent
(Optional)

Specifies the extent of the data that will be evaluated by this tool.

  • MAXOF—The maximum extent of all inputs will be used.
  • MINOF—The minimum area common to all inputs will be used.
  • DISPLAY—The extent is equal to the visible display.
  • Layer name—The extent of the specified layer will be used.
  • Extent object—The extent of the specified object will be used.
  • Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max.
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.

arcpy.env.workspace = "C:/data"
arcpy.SurfaceDifference_3d("sample.gdb/lidar/terrain", "flood_tin", "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

# Set environment settings
arcpy.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)

Licensing information

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

Related topics