ArcGIS REST API

Calculate Volume

  • URL:https://<imageservice-url>/calculateVolume
  • Required Capability:Image
  • Version Introduced:10.7

Description

License:

As of 10.5, you must license your ArcGIS Server as an ArcGIS Image Server to use this resource with a mosaic dataset.

This operation is supported at 10.7 and later.

The calculateVolume operation is performed on an image service resource that uses ArcObjects11 or ArcObjectsRasterRendering as the service provider. Since this operation is designed to run with an elevation image service, the “esriImageServiceDataTypeElevation” image service data type is required.

This operation performs a volumetric calculation on the elevation data. Results are in square meters for area calculation and in cubic meters for volume calculation by default. If the elevation image service does not have vertical spatial reference and the vertical z-unit is not meters, additional unit conversion is needed when interpreting the results.

The result of this operation includes a 2D area of the base surface, volumes that needs to be cut or filled toward the target base surface, and the statistics of elevation values on the given geometry's vertices.

You can provide arguments to the calculateVolume operation as query parameters defined in the parameters table below.

Request parameters

ParameterDetails
f

Description: The response format. The default response format is html.

Values: html | json

geometry

(Required)

A geometry that defines the area of interest. The location can be an envelope or a polygon. The structure of the geometry is the same as the structure of the JSON geometry objects.

geometryType

(Required)

The type of geometry specified by the geometry parameter. The geometry type can be an envelope or a polygon.

Value: esriGeometryEnvelope | esriGeometryPolygon

mosaicRule

Specifies the mosaic rule for how individual image items in the requested image service will be mosaicked. This determines the elevation values on overlapped elevation image pixels.

Refer to the mosaic rule JSON objects for the syntax and examples.

pixelSize

The image items that are visible at the specified pixel size will be used for volume calculation. If pixelSize is not specified, all image items of the image service at all resolutions will be used.

The structure of the pixelSize parameter is the same as the structure of the point object. In addition to the JSON structure, you can specify the pixel size with a simple comma-separated syntax.

Syntax:

  • JSON structure: pixelSize={point}
  • Point simple syntax: pixelSize=<x>,<y>

Examples:

  • pixelSize={"x": 0.18, "y": 0.18}
  • pixelSize=0.18,0.18

baseType

Description: Surface type of the base elevation plane:

0—Constant z

1—Best fitting plane

2—Lowest elevation on the perimeter

3—Highest elevation on the perimeter

2—Average elevation on the perimeter

constantZ

Description: If the baseType parameter is 0 (constant z), this parameter is needed to define the elevation plane for performing the volume calculation.

Example usage

Calculate cut and fill volumes with a 2D polygon at a certain target base surface elevation.

itemIds=i9d41856c-3636-4580-b796-7091cc069afb,i00ffedac-6b57-4afa-91b4-b74592c26192&rasterType=Raster Dataset&maximumCellSizeFactor=10&f=json

Add one JPEG with polynomial transformation to an image service through http://myserver/arcgis/rest/sampleImage/ImageServer/add, post request content:

https://myserver:6443/arcgis/rest/services/myElevationIS/ImageServer/calculateVolume?geometries=[{"rings":[[[-79.85557925358401,43.33951463577869],[-79.85557925358401,44.228527462651435],[-78.85717076732973,44.228527462651435],[-78.85717076732973,43.33951463577869],[-79.85557925358401,43.33951463577869]]],"spatialReference":{"wkid":4269}}] &geometryType=esriGeometryPolygon&baseType=0&mosaicRule=&constantZ=500&pixelSize=&f=html

JSON response syntax

{"results": [{
 "area": <area_ring_1>,
 "cut": <cut_ring_1>,
 "fill": <fill_ring_1>,
 "minz": <minz_ring_1>,
 "maxz": <maxz_ring_1>,
 "meanz": <meanz_ring_1>
},{
 "area": <area_ring_2>,
 "cut": <cut_ring_2>,
 "fill": <fill_ring_2>,
 "minz": <minz_ring_2>,
 "maxz": <maxz_ring_2>,
 "meanz": <meanz_ring_2>
}
…
]}

JSON response example

{"results": [{
 "area": 0.8875979507386519,
 "cut": 0,
 "fill": -289.7427368055556,
 "minz": 73,
 "maxz": 247.8786334562855,
 "meanz": 184.59350068111561
}]}