Surface Volume (3D Analyst Tools)

Summary

Calculates the area and volume of the region between a surface and a reference plane.

Illustration

Surface Volume tool illustration

Usage

Use the Z Factor parameter to ensure the accuracy of volume calculations when the surface z-values are in a different unit of measure than the x,y units. The Z Factor parameter will not modify the original data. The tool will automatically determine the appropriate z-factor when the x,y- and z-coordinate systems are defined.

The output text file will store the full path to the surface, the parameters used to generate results, and the calculated area and volume measurements. If the same output file is specified in multiple runs of the tool, the pre-existing records are maintained and the results are appended to the table as shown in the following example:


Dataset	Plane Height	Reference	Z Factor	Area 2D	Area 3D	Volume
C:\data\tin	100.00	Above	1	15984467.82	16354331.40	1886012931.05
C:\data\raster.tif	250.5	Below	3.28084	0	0	0
C:\data.gdb\fd\terrain	1250	Above	0.3048	1854238.36	1970550.88	1099221466.89

When the region for the calculations is a nonrectangular extent, use a polygon to define the region. Then use the Polygon Volume tool to determine the calculations.
A raster surface is evaluated using the extent of the center point of each cell, as opposed to the extent of the entire cell area. The resulting analysis will decrease the data area of the raster by half a cell relative to the data area displayed for the raster.

Label	Explanation	Data type
Input Surface	The raster, TIN, or terrain surface that will be processed.	Mosaic Layer; Raster Layer; Terrain Layer; TIN Layer
Output Text File (Optional)	A comma-delimited ASCII text file containing the area and volume calculations. If the file already exists, the results will be appended to the file.	File
Reference Plane (Optional)	Specifies the direction from the reference plane that will be used to calculate the results. Above the Plane—Volume and area calculations will represent the region of space between the specified plane height and the portions of the surface that are above the plane. This is the default. Below the Plane—Volume and area calculations will represent the region of space between the specified plane height and the portions of the surface that are below the plane.	String
Plane Height (Optional)	The z-value of the plane that will be used to calculate area and volume.	Double
Z Factor (Optional)	The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.	Double
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

arcpy.3d.SurfaceVolume(in_surface, {out_text_file}, {reference_plane}, {base_z}, {z_factor}, {pyramid_level_resolution})

Name	Explanation	Data type
in_surface	The raster, TIN, or terrain surface that will be processed.	Mosaic Layer; Raster Layer; Terrain Layer; TIN Layer
out_text_file (Optional)	A comma-delimited ASCII text file containing the area and volume calculations. If the file already exists, the results will be appended to the file.	File
reference_plane (Optional)	Specifies the direction from the reference plane that will be used to calculate the results. `ABOVE`—Volume and area calculations will represent the region of space between the specified plane height and the portions of the surface that are above the plane. This is the default. `BELOW`—Volume and area calculations will represent the region of space between the specified plane height and the portions of the surface that are below the plane.	String
base_z (Optional)	The z-value of the plane that will be used to calculate area and volume.	Double
z_factor (Optional)	The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.	Double
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

Code sample

SurfaceVolume example 1 (Python window)

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

arcpy.env.workspace = "C:/data"
arcpy.ddd.SurfaceVolume("sample.gdb/featuredataset/terrain", "surf_vol.txt",
                       reference_plane="ABOVE", base_z=300, z_factor=3.24,
                       pyramid_level_resolution=5)

SurfaceVolume example 2 (stand-alone script)

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

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

****************************************************************************'''
# Import system modules
import arcpy

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

# Set Local Variables
inSurface = "elevation_tin"

# Run SurfaceVolume
result = arcpy.ddd.SurfaceVolume(inSurface, "", "ABOVE", "300", "1", "5")
print(result.getMessages())

Environments

Current Workspace

Licensing information

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