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.

Parameters

LabelExplanationData Type
Input Surface

The triangulated surface whose relative displacement is being evaluated from the reference surface.

LAS Dataset Layer; Terrain Layer; TIN Layer
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
Output 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
Analysis 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 Analysis 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
Output 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
Output 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
Output TIN Base Name
(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
LAS Thinning 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.
  • MinimumThe LAS point with the smallest z-value among all the LAS points in the analysis window.
  • MaximumThe LAS point with the highest z-value among all the LAS points in the analysis window.
String
Reference LAS Thinning 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.
  • MinimumThe LAS point with the smallest z-value among all the LAS points in the analysis window.
  • MaximumThe LAS point with the highest z-value among all the LAS points in the analysis window.
String
Processing Extent
(Optional)

The extent of the data that will be evaluated.

  • Current Display Extent Map View—The extent will be based on the active map or scene. This option is only available when there is an active map.
  • Draw Extent Square and Finish—The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map.
    Note:

    This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box.

    Note:

    When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent.

  • Extent of a Layer Layer—The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers.

    Each map layer has the following options:

    • All Features Select All—The extent of all features in the layer.
    • Selected Features Area from Selected Features—The extent of the selected features in the layer.
    • Visible Features Extent Indicator—The extent of visible features in the layer.
      Note:

      The extents from the Selected Features Area from Selected Features and Visible Features Extent Indicator options are only available for feature layers.

  • Browse Browse—The extent will be based on an existing dataset.
  • Intersection of Inputs Intersect—The extent will be based on the minimum or intersecting extent of all inputs. If no inputs overlap, a null extent with all zeros will result.
  • Union of Inputs Union—The extent will be based on the maximum or combined extent of all inputs.
  • Clipboard Paste—The extent can be copied to and from the clipboard.
    • Copy Extent Copy—Copies the extent coordinates and coordinate system to the clipboard.
    • Paste Extent Paste—Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system.
    Note:

    The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference.

  • Reset Extent Reset—The extent will be reset to the default value.
  • Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system.
    Caution:

    The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.

Extent
Processing Boundary

A polygon feature that will define the area of interest to be processed.

Feature Layer

arcpy.ddd.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)
NameExplanationData 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)

The extent of the data that will be evaluated.

  • 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 will define the area of interest to be processed.

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.ddd.SurfaceDifference("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.ddd.SurfaceDifference(inSurface, inReference, outPoly)

Licensing information

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

Related topics