Polygon Volume (3D Analyst)

Summary

Calculates the volume and surface area between a polygon of a constant height and a surface.

Usage

  • First, each polygon will intersect the surface. Then volume and surface calculations will be made for all surface triangles and portions of triangles that fall within the intersected polygon. If calculations based on an extent are suitable for your needs, you can use the Surface Volume tool for faster results.

  • The surface area represents the portions of the surface that are above or below the height of the polygon features. The volume represents the region between the surface and the space above or below the height of the polygon feature. When calculations are made above the plane, the volume represents the region between the plane and the underside of the surface. When calculations are made below the plane, the volume represents the region between the plane and the topside of the surface.

  • The input surface is evaluated as a triangulated irregular network (TIN). A LAS dataset is processed as a surface by constructing a TIN from the LAS dataset. Since LAS datasets typically contain a large amount of points, the construction of the intermediate surface that is used for analysis can take a significant amount of time for processing when the input polygon covers a large number of points. In this case, you can export a thinned TIN from the LAS dataset using the LAS Dataset To TIN tool.

Parameters

LabelExplanationData Type
Input Surface

The TIN, terrain, or LAS dataset surface that will be processed.

LAS Dataset Layer; Terrain Layer; TIN Layer
Input Polygons

The polygon features that define the region being processed.

Feature Layer
Height Field

The field in the polygon's attribute table that defines the height of the reference plane that will be used in determining volumetric calculations.

String
Reference Plane
(Optional)

Specifies the direction from the reference plane that volume and surface area will be calculated.

  • Calculate above the planeVolume and surface area will be calculated above the reference plane height of the polygons.
  • Calculate below the planeVolume and surface area will be calculated below the reference plane height of the polygons. This is the default.
  • Calculate above and below the planeVolume and surface area will be calculated above and below the reference plane height of the polygons.
String
Volume Field
(Optional)

The name of the field that will contain volumetric calculations. The default is Volume.

String
Surface Area Field
(Optional)

The name of the field that will contain the surface area calculations. The default is SArea.

String
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
Volume Field
(Optional)

The name of the field that will contain the volume calculated above the polygon height. The default is Above_Vol.

String
Volume Field
(Optional)

The name of the field that will contain the volume calculated below the polygon height. The default is Below_Vol.

String
Surface Area Above Field
(Optional)

The name of the field that will contain the surface area calculated above the polygon height. The default is Above_SA.

String
Surface Area Below Field
(Optional)

The name of the field that will contain the surface area calculated below the polygon height. The default is Below_SA.

String

Derived Output

LabelExplanationData Type
Output Feature Class

The output features that will be updated.

Feature Layer

arcpy.ddd.PolygonVolume(in_surface, in_feature_class, in_height_field, {reference_plane}, {out_volume_field}, {surface_area_field}, {pyramid_level_resolution}, {out_volume_above_field}, {out_volume_below_field}, {surface_area_above_field}, {surface_area_below_field})
NameExplanationData Type
in_surface

The TIN, terrain, or LAS dataset surface that will be processed.

LAS Dataset Layer; Terrain Layer; TIN Layer
in_feature_class

The polygon features that define the region being processed.

Feature Layer
in_height_field

The field in the polygon's attribute table that defines the height of the reference plane that will be used in determining volumetric calculations.

String
reference_plane
(Optional)

Specifies the direction from the reference plane that volume and surface area will be calculated.

  • ABOVEVolume and surface area will be calculated above the reference plane height of the polygons.
  • BELOWVolume and surface area will be calculated below the reference plane height of the polygons. This is the default.
  • BOTHVolume and surface area will be calculated above and below the reference plane height of the polygons.
String
out_volume_field
(Optional)

The name of the field that will contain volumetric calculations. The default is Volume.

String
surface_area_field
(Optional)

The name of the field that will contain the surface area calculations. The default is SArea.

String
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
out_volume_above_field
(Optional)

The name of the field that will contain the volume calculated above the polygon height. The default is Above_Vol.

String
out_volume_below_field
(Optional)

The name of the field that will contain the volume calculated below the polygon height. The default is Below_Vol.

String
surface_area_above_field
(Optional)

The name of the field that will contain the surface area calculated above the polygon height. The default is Above_SA.

String
surface_area_below_field
(Optional)

The name of the field that will contain the surface area calculated below the polygon height. The default is Below_SA.

String

Derived Output

NameExplanationData Type
output_feature_class

The output features that will be updated.

Feature Layer

Code sample

PolygonVolume example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

arcpy.env.workspace = "C:/data"
arcpy.ddd.PolygonVolume("sample.gdb/featuredataset/terrain", "cut_off_plane.shp", 
                       in_height_field="Z", reference_plane="ABOVE", 
                       pyramid_level_resolution="5")
PolygonVolume example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

'''****************************************************************************
Name: PolygonVolume Example
Description: This script demonstrates how to use the 
             PolygonVolume tool.
****************************************************************************'''

# Import system modules
import arcpy
from arcpy import env

# Set environment settings
env.workspace = "C:/data"


# Set Local Variables
inSurface = "sample.gdb/featuredataset/terrain"
inPoly = "floodplain_100.shp"
zField = "Height"
refPlane = "BELOW"
volFld = "Volume"
sAreaFld = "SArea"

#Execute PolygonVolume
arcpy.ddd.PolygonVolume(inSurface, inPoly, zField, refPlane, volFld, sAreaFld)

Licensing information

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

Related topics