| Label | Explanation | Data Type |
Input Surface | The raster, TIN, or terrain surface to process. | 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 new results will be appended to the file. | File |
Reference Plane (Optional) | The direction from the reference plane for which to calculate the results.
| 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 |
Summary
Calculates the area and volume of the region between a surface and a reference plane.
Illustration
Usage
Apply a Z Factor to ensure the accuracy of volume calculations when the surface Z values are expressed in a different unit of measure than the XY units. Using a Z Factor will not modify the original data. The tool will automatically determine the appropriate Z-factor when the XY 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.
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
If the region for which surface area and volumetric calculations are desired is defined by a non-rectangular extent, consider creating a polygon to delineate the boundary of the area of interest, then use the Polygon Volume tool to determine the calculations for the region between the plane defined by the polygon and a given surface.
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.
Parameters
arcpy.ddd.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 to process. | 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 new results will be appended to the file. | File |
reference_plane (Optional) | The direction from the reference plane for which to calculate the results.
| 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
The following sample demonstrates the use of this tool in the Python window.
arcpy.env.workspace = "C:/data"
arcpy.SurfaceVolume_3d("sample.gdb/featuredataset/terrain", "surf_vol.txt",
reference_plane="ABOVE", base_z=300, z_factor=3.24,
pyramid_level_resolution=5)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"
# Execute SurfaceVolume
result = arcpy.SurfaceVolume_3d(inSurface, "", "ABOVE", "300", "1", "5")
print(result.getMessages())Environments
Licensing information
- Basic: Requires 3D Analyst
- Standard: Requires 3D Analyst
- Advanced: Requires 3D Analyst