Storage Capacity (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Creates a table and a chart of elevations and corresponding storage capacities for an input surface raster. The tool calculates the surface area and total volume of the underlying region at a series of elevation increments.

Usage

• The tool creates a table of surface area and total volumes at a series of elevation increments. The table contains a record for every elevation increment for each zone.

  The output table has the following schema:

  • The fields are ELEVATION, AREA, and VOLUME.
  • The area and volume fields contain the storage capacity calculations at each elevation increment.
  • The elevation and volume fields are calculated in z-units. The area field is calculated in the x,y units of the input surface raster.
  • When no zones are specified, a ZONE_CODE field is added with a value of 1 for all records using the analysis extent as a single zone.
  • If zones are specified, a field is added based on the Zone field parameter value (zone_field in Python). For an integer zone field, a field will be added with the same name in the output table. For a string zone field, a field will be added with the same name in the output table and an additional field ZONE_CODE will be added.

• Two charts are optionally created to plot elevation area and elevation volume curves. The charts are added to the Contents pane along with the output table. The naming convention used for the chart name is <out_chart> Elevation Area Curve and <out_chart> Elevation Volume Curve, where <out_chart> is replaced with the name specified in the Output chart name parameter (out_chart in Python). When creating a chart with multiple zones, each line in the chart represents a zone. Use the legend to interactively turn lines on or off in the chart. See Charts quick tour for details about working with charts in ArcGIS AllSource. The charts can only be created in ArcGIS AllSource; they are not supported from a stand-alone script.

• Use the Analysis type parameter (analysis_type in Python) to select surface area, volume calculations, or both. This determines the schema for tables and charts. For example, if the Area option (AREA in Python) is selected, only an area field is created in the output table and the volume field is omitted. Likewise, only one chart is created for the area elevation curve.

• If no zones are specified, storage capacity is calculated using the analysis extent as a single zone. Specify an optional Input raster or feature zone data parameter value (in_zone_data in Python) that represents the zones where storage capacities need to be calculated. For example, a zone can be a reservoir or a detention basin. The tool supports calculations across multiple zones, and storage capacities are calculated independently at each zone based on a zone field.

• The elevation increments on which storage capacities are calculated are based on the Minimum elevation (min_elevation in Python), Maximum elevation (max_elevation in Python), Increment type (increment_type in Python), and Increment (increment in Python) parameter values.

• The default Minimum elevation and Maximum elevation parameter values are determined as follows:

  • The tool uses the minimum and maximum zonal values from the input surface raster as default values. These values can vary from zone to zone depending on the minimum and maximum values of the input surface raster in these zones.
  • If you specify a Minimum elevation or Maximum elevation parameter value, the tool uses the same value for minimum and maximum increments across all zones. In this case, if a subset of elevation increments becomes smaller than the zonal minimum, the area and volumes are calculated as zero. If they become larger than the zonal maximum, areas and volumes for those increments are not calculated and appear as null or zero depending on the table format.

• Specify a Z unit (z_unit in Python) parameter value to indicate the input surface raster's vertical units. If the input surface raster has a vertical coordinate system specified, these units are used as the default z-unit. If no z-unit is specified and the input surface raster does not have a vertical coordinate system, the default z-unit is meter. When the x,y units are different from the z-unit, the x,y units are converted to match the z-unit when calculating volumes.

• By default, this tool will use multicore processors if available. The maximum number of cores that can be used is four.

  To use fewer cores, use the Parallel Processing Factor environment setting.

Parameters

Dialog

Label	Explanation	Data Type
Input surface raster	The input raster representing a continuous surface.	Raster Layer
Output table	The output table that contains for each zone the surface area and total volumes for each increment in elevation.	Table
Input raster or feature zone data	The dataset that defines the zones. The zones can be defined by an integer raster or a feature layer.	Raster Layer; Feature Layer
Zone field (Optional)	The field that contains the values that define each zone. It can be an integer or a string field of the zone dataset.	Field
Analysis type (Optional)	Specifies the analysis type. Area and Volume—Both surface areas and total volumes are calculated at each elevation increment. This is the default. Area—Surface area is calculated at each elevation increment. Volume—Total volume is calculated at each elevation increment.	String
Minimum elevation (Optional)	The minimum elevation from which storage capacities are assessed. By default, the tool uses the minimum surface raster value in each zone as the minimum elevation for that zone. If a value is provided, it is used as the minimum elevation across all zones.	Double
Maximum elevation (Optional)	The maximum elevation from which storage capacities are assessed. By default, the tool uses the maximum surface raster value in each zone as the maximum elevation for that zone. If a value is provided, it is used as the maximum elevation across all zones.	Double
Increment type (Optional)	Specifies the increment type to use when computing elevation increments between minimum and maximum elevations. Number of Increments—The number of increments between minimum and maximum elevations is used. This is the default. Value of Increment—The elevation difference between each increment is used.	String
Increment (Optional)	An incremental value that is either the number of increments or the difference in elevation between increments. The value is determined based on the increment type parameter value.	Double
Z unit (Optional)	Specifies the linear unit that will be used for vertical z-values. Inch—The linear unit will be inches. Foot—The linear unit will be feet. Yard—The linear unit will be yards. Mile US—The linear unit will be miles. Nautical mile—The linear unit will be nautical miles. Millimeter—The linear unit will be millimeters. Centimeter—The linear unit will be centimeters. Meter—The linear unit will be meters. Kilometer—The linear unit will be kilometers. Decimeter—The linear unit will be decimeters.	String
Output chart name (Optional)	The name of the output chart for display. The chart is listed in the Contents pane under Standalone Tables.	Chart

Python

StorageCapacity(in_surface_raster, out_table, in_zone_data, {zone_field}, {analysis_type}, {min_elevation}, {max_elevation}, {increment_type}, {increment}, {z_unit}, {out_chart})

Name	Explanation	Data Type
in_surface_raster	The input raster representing a continuous surface.	Raster Layer
out_table	The output table that contains for each zone the surface area and total volumes for each increment in elevation.	Table
in_zone_data	The dataset that defines the zones. The zones can be defined by an integer raster or a feature layer.	Raster Layer; Feature Layer
zone_field (Optional)	The field that contains the values that define each zone. It can be an integer or a string field of the zone dataset.	Field
analysis_type (Optional)	Specifies the analysis type. AREA_VOLUME—Both surface areas and total volumes are calculated at each elevation increment. This is the default. AREA—Surface area is calculated at each elevation increment. VOLUME—Total volume is calculated at each elevation increment.	String
min_elevation (Optional)	The minimum elevation from which storage capacities are assessed. By default, the tool uses the minimum surface raster value in each zone as the minimum elevation for that zone. If a value is provided, it is used as the minimum elevation across all zones.	Double
max_elevation (Optional)	The maximum elevation from which storage capacities are assessed. By default, the tool uses the maximum surface raster value in each zone as the maximum elevation for that zone. If a value is provided, it is used as the maximum elevation across all zones.	Double
increment_type (Optional)	Specifies the increment type to use when computing elevation increments between minimum and maximum elevations. NUMBER_OF_INCREMENTS—The number of increments between minimum and maximum elevations is used. This is the default. VALUE_OF_INCREMENT—The elevation difference between each increment is used.	String
increment (Optional)	An incremental value that is either the number of increments or the difference in elevation between increments. The value is determined based on the increment type parameter value.	Double
z_unit (Optional)	Specifies the linear unit that will be used for vertical z-values. INCH—The linear unit will be inches. FOOT—The linear unit will be feet. YARD—The linear unit will be yards. MILE_US—The linear unit will be miles. NAUTICAL_MILE—The linear unit will be nautical miles. MILLIMETER—The linear unit will be millimeters. CENTIMETER—The linear unit will be centimeters. METER—The linear unit will be meters. KILOMETER—The linear unit will be kilometers. DECIMETER—The linear unit will be decimeters.	String
out_chart (Optional)	The name of the output chart for display.	Chart

Code sample

StorageCapacity example 1 (Python window)

Use the StorageCapacity tool to create a table of surface areas and total volumes at 10 elevation increments in an input surface raster for each zone in a zone feature.

import arcpy
from arcpy.sa import *
arcpy.env.workspace = "C:/sapyexamples/data"
arcpy.sa.StorageCapacity("in_surface.tif", "out_table", "in_zones", "zone_id")

StorageCapacity example 2 (stand-alone script)

Use the StorageCapacity tool to create a table of surface areas and total volumes at 10 elevation increments in an input surface raster for each zone in a zone feature.

# Name: StorageCapacity_Standalone.py
# Description: 
# Requirements: Spatial Analyst Extension

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

# Set the analysis environments
arcpy.CheckOutExtension("Spatial")
arcpy.env.workspace = "C:/arcpyExamples/data"

# Set local variables
in_surface_raster = "in_surface.tif"
out_table = "fgdb.gdb\out_table"
in_zones = "fgdb.gdb\in_zones"
zone_field = "zone_id"

# Execute StorageCapacity tool
arcpy.sa.StorageCapacity(in_surface_raster, out_table, in_zones, zone_field)

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size