Calculate Cut Fill Volume (Image Analyst Tools)

Summary

Calculates the cut and fill volumes between a base elevation surface and an elevation raster. A cut and fill raster can also be generated. The base elevation surface can be specified with different types, such as a feature class containing one or more polygons, a polygon array, a JSON string or file, or a raster.

Usage

The Output Cut Fill Raster parameter value is a raster dataset comprised of areas depicting areas where material has been removed (cut), and areas where material has been added (fill). Click the output cut fill raster dataset to display the cut and fill information in the Image Information pane.
In the Output Cut Fill Raster parameter value, the volume values for cut areas are positive, and fill areas are negative values. For example, a pixel value of -0.000305 means cubic meters fill.
When the input Base Surface parameter value is polygons, the enabled Base Surface Type parameter options are Surface, Minimum, Maximum, Mean, Constant Z, and Geometry Z.
The Output Volume Info parameter value will contain the cut and fill volume information in a .txt or .json file. A sample output is listed below:
```
[
  {
    "area" : 19009.705386691581,
    "cut" : 19216.883079243154,
    "fill" : -31352.230228323864,
    "cutCellCount" : 668750,
    "fillCellCount" : 936135,
    "minz" : 24.048617219013618,
    "maxz" : 239.59296198262672,
    "meanz" : 127.5100044561793
  }
]
```
The information in the file is organized as follows:
- area—The area in square meters
- cut—The cut volume in cubic meters
- fill—The fill volume in cubic meters
- cutCellCount—The number of cut cells
- fillCellCount—The number of fill cells
- minz—The minimum elevation value in meters
- maxz—The maximum elevation value in meters
- meanz—The mean elevation value in meters

Label	Explanation	Data type
Input DSM	The input digital surface model (DSM) elevation raster. This input DSM raster is compared with the base elevation raster.	Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; Image Service
Base Surface	The base elevation surface that will be used for calculating cut and fill volumes. The base elevation surface supports different types, such as a feature class containing one or more polygons, a polygon array, a JSON string or file, or a raster.	Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; Image Service; Feature Class; Feature Layer; String; File
Base Surface Type	Specifies the base surface type that will be used for the base surface. Surface—The height values of the input DSM at the polygon's vertex's location will be used to construct the base surface. Minimum—The minimum height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. Maximum—The maximum height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. Mean—The average height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. Constant Z—The constant z-value will be used as the base surface. Geometry Z—The z-value of the 3D geometry vertices will be used to construct the base surface. If this option is used with a feature class without elevation, the height value from the Input DSM parameter value will be used. DSM—A DSM will be used as the base surface.	String
Constant Z (Optional)	The value that will be used to define the elevation plane for performing the volume calculation. This parameter is active when the Base Surface Type parameter is set to Constant Z.	Linear Unit
Output Volume Info (Optional)	The output file with cut and fill volume information. The file can be a `.txt` file or `.json` file. The results will be in square meters for area calculations and in cubic meters for volume calculations.	File
Output Cut Fill Raster (Optional)	The output cut and fill volume raster. Provide a file extension to denote different formats for the raster dataset. The parameter supports commonly use raster types, such as `.tif`, `.crf`, `.img`, GRID, and file geodatabase raster.	Raster Dataset

CalculateCutFillVolume(in_raster, in_base_surface, base_surface_type, {constant_z}, {out_volume_info}, {out_cut_fill_raster})

Name	Explanation	Data type
in_raster	The input digital surface model (DSM) elevation raster. This input DSM raster is compared with the base elevation raster.	Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; Image Service
in_base_surface	The base elevation surface that will be used for calculating cut and fill volumes. The base elevation surface supports different types, such as a feature class containing one or more polygons, a polygon array, a JSON string or file, or a raster.	Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; Image Service; Feature Class; Feature Layer; String; File
base_surface_type	Specifies the base surface type that will be used for the base surface. `SURFACE`—The height values of the input DSM at the polygon's vertex's location will be used to construct the base surface. `MINIMUM`—The minimum height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. `MAXIMUM`—The maximum height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. `MEAN`—The average height value of the input DSM for the perimeter of the base surface polygon will be used as the base surface. `CONSTANTZ`—The constant z-value will be used as the base surface. `GEOMETRYZ`—The z-value of the 3D geometry vertices will be used to construct the base surface. If this option is used with a feature class without elevation, the height value from the `in_raster` parameter value will be used. `DSM`—A DSM will be used as the base surface.	String
constant_z (Optional)	The value that will be used to define the elevation plane for performing the volume calculation. This parameter is enabled when the `base_surface_type` parameter is set to `CONSTANTZ`.	Linear Unit
out_volume_info (Optional)	The output file with cut and fill volume information. The file can be a `.txt` file or `.json` file. The results will be in square meters for area calculations and in cubic meters for volume calculations.	File
out_cut_fill_raster (Optional)	The output cut and fill volume raster. Provide a file extension to denote different formats for the raster dataset. The parameter supports commonly use raster types, such as `.tif`, `.crf`, `.img`, GRID, and file geodatabase raster.	Raster Dataset

Code sample

CalculateCutfillVolume example 1 (Python window)

This example calculates volume information using a polygon array JSON string as the base surface.

# Import system modules
import arcpy
from arcpy.ia import *

arcpy.ia.CalculateCutfillVolume(in_raster=r"C:\Data\YVWD_dsm.crf", in_base_surface='{"objectIdFieldName":"OBJECTID","fields":[{"name":"OBJECTID","type":"esriFieldTypeOID","alias":"OBJECTID","domain":null},{"name":"Shape","type":"esriFieldTypeGeometry","alias":"Shape","domain":null},{"name":"id","type":"esriFieldTypeInteger","alias":"ID","domain":null},{"name":"name","type":"esriFieldTypeString","alias":"NAME","domain":null},{"name":"baseType","type":"esriFieldTypeInteger","alias":"BASE SURFACE TYPE","domain":{"type":"codedValue","name":"VolumeBaseSurfaceType","description":"Base surface types for volume calculation.","codedValues":[{"name":"Costant Z","code":0},{"name":"Best Fit","code":1},{"name":"Minimum Z","code":2},{"name":"Maximum Z","code":3},{"name":"Average Z","code":4}],"mergePolicy":"esriMPTDefaultValue","splitPolicy":"esriSPTDefaultValue"}},{"name":"constantZ","type":"esriFieldTypeDouble","alias":"CONSTANT Z","domain":null},{"name":"area","type":"esriFieldTypeDouble","alias":"AREA","domain":null},{"name":"minz","type":"esriFieldTypeDouble","alias":"MINIMUM Z","domain":null},{"name":"maxz","type":"esriFieldTypeDouble","alias":"MAXIMUM Z","domain":null},{"name":"meanz","type":"esriFieldTypeDouble","alias":"MEAN Z","domain":null},{"name":"cut","type":"esriFieldTypeDouble","alias":"CUT","domain":null},{"name":"fill","type":"esriFieldTypeDouble","alias":"FILL","domain":null}],"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":102100,"latestWkid":3857},"features":[{"geometry":{"rings":[[[-13034818.299460374,4029761.0475366744],[-13034772.914974842,4029762.241865241],[-13034776.497960543,4029728.5020832345],[-13034835.915806731,4029729.3978296597],[-13034818.299460374,4029761.0475366744]]],"spatialReference":{"wkid":102100,"latestWkid":3857}},"attributes":{"id":1,"name":"AOI 1","baseType":0,"constantZ":90,"area":1172.3330906432095,"minz":626.8749025576568,"maxz":629.5470508029413,"meanz":627.6681208213765,"cut":631398.5623827629,"fill":0}}]}', base_surface_type="MINIMUM",
constant_z=300,
out_volume_info=r"C:\cutfill\volume.json",
out_cut_fill_raster=r"C:\cutfill\CutFillRaster.crf")

CalculateCutfillVolume example 2 (stand-alone script)

This example calculates volume using a polygon feature class as the base surface.

# Import system modules
import arcpy
from arcpy.ia import *

# Define parameters.
in_raster = r"C:\Data\YVWD_dsm.crf"
in_base_surface = r"C:\Data\YVWD.gdb\AOI_2D"
base_surface_type = "SURFACE"
constant_z = "None"
out_volume_info = r"C:\Output\volume.json"
out_cut_fill_raster = r"C:\Data\YVWD.gdb\CutFillRaster"

# Run CalculateVolume
arcpy.ia.CalculateCutfillVolume(in_raster, in_base_surface, base_surface_type, constant_z, out_volume_info, out_cut_fill_raster)

Environments

This tool does not use any geoprocessing environments.

Licensing information