VolumeMeasurementAnalysis | References | ArcGIS Maps SDK for JavaScript

import VolumeMeasurementAnalysis from "@arcgis/core/analysis/VolumeMeasurementAnalysis.js";

Inheritance:: VolumeMeasurementAnalysis→Analysis→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.34

beta

VolumeMeasurementAnalysis is currently in beta. To learn about features in beta, see the Frequently Asked Questions.

VolumeMeasurementAnalysis calculates and visualizes the volume of ground surfaces within a defined polygonal area, offering multiple measure types and displaying results in a 3D SceneView.

The measure type is set with the measureType property, and can be further customized using optional, type-specific options.

To display a volume measurement of a ground surface bounded by a given Polygon:

Create a new instance of VolumeMeasurementAnalysis.
Set the measureType property.
Set the geometry property to the given Polygon instance.
If using the "cut-fill" measureType, optionally set custom properties with VolumeMeasurementCutFillOptions.
Add the VolumeMeasurementAnalysis instance to SceneView.analyses.

Use the VolumeMeasurementAnalysisView3D to retrieve the analysis result.

// create analysis
const volumeMeasurementAnalysis = new VolumeMeasurementAnalysis({
  measureType: "stockpile", // if not set it defaults to "cut-fill"
  geometry: new Polygon({ }),
});

// add to scene view
view.analyses.add(volumeMeasurementAnalysis);

// retrieve the result from the analysis view once available
const analysisView = await view.whenAnalysisView(volumeMeasurementAnalysis);
await reactiveUtils.whenOnce(() => analysisView.result);

const result = analysisView.result;

To draw a volume measurement polygon interactively, use the VolumeMeasurementAnalysisView3D.place() method.

// cancel the placement operation at some later point
// by calling abortController.abort()
const abortController = new AbortController();

try {
  await analysisView.place({ signal: abortController.signal });
} catch (error) {
  if (error.name === "AbortError") {
    console.log("Placement operation was cancelled.");
  }
}

The analysis depends on the scene's spatial reference, and the length of the measured perimeter:

In Projected Coordinate Systems (PCS), apart from Web Mercator used in local viewing mode, there is no limit to the measurement's perimeter, making it the recommended setup for analysis as accuracy is not compromised.
In Web Mercator PCS used in local viewing mode, if the measurement's perimeter exceeds 10 km, the analysis is considered invalid due to potential accuracy issues.
In Geographic Coordinate Systems (GCS) and Web Mercator in global viewing mode, if the measurement's perimeter exceeds 50 km, the analysis is considered invalid due to potential accuracy issues.

In certain situations (including information in Known Limitations below), the analysis result cannot be computed. Refer to the VolumeMeasurementAnalysisView3D.error property for more information.

Known Limitations

This analysis is only supported in a 3D SceneView.
The results of the tool vary depending on the zoom level, as changes in zoom level affect the level of detail (LOD) of the scene geometry.
If the view is too close or too far from the measurement polygon, the results will not be computed due to LOD-induced inaccuracies.
The target elevation ("cut-fill" measureType) is restricted to the range between -11 km and +9 km.
This analysis operates only on the non-transparent Map.ground, IntegratedMeshLayer and an IntegratedMesh3DTilesLayer.
This analysis does not support WGS 1984 spatial reference in a local viewing mode.

See also

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`VolumeMeasurementAnalysisProperties`

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`cutFillOptions`	`VolumeMeasurementCutFillOptions`
`declaredClass` readonly inherited	`string`	Accessor
`displayUnits`	`VolumeMeasurementDisplayUnits`
`geometry`	`Polygon \| null \| undefined`
`id` readonly inherited	`string`	Analysis
`inputUnits`	`VolumeMeasurementInputUnits`
`measureType`	`VolumeMeasureType`
`origin` inherited	`AnalysisOriginWebScene \| null \| undefined`	Analysis
`type` readonly	`"volume-measurement"`
`uid` readonly inherited	`string`	IdentifiableMixin
`valid` readonly	`boolean`

cutFillOptions

autocast Property

Type: VolumeMeasurementCutFillOptions

The configuration used when the measureType is set to "cut-fill".

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

displayUnits

autocast Property

Type: VolumeMeasurementDisplayUnits

Units used for displaying values in the UI.

geometry

autocast Property

Type: Polygon | null | undefined

A polygon that defines the boundary for volume measurement computations and visualizations for all measure types.

If the polygon has z-values these will be ignored as the polygon will be projected on the ground.

id

readonlyinherited Property

Type: string

Inherited from: Analysis

A user settable identifier for the analysis. A unique value is automatically generated when the analysis is created if it is not set explicitly during construction.

inputUnits

autocast Property

Type: VolumeMeasurementInputUnits

Units used for interpreting input values.

measureType

Property

Type: VolumeMeasureType

Specifies the desired volume measure type.

Mode	Description
"cut-fill"	Computes cut and fill volumes relative to a flat, horizontal surface defined by the input polygon. VolumeMeasurementCutFillOptions allows setting the elevation of the target surface and the unit of elevation.
"stockpile"	Calculates cut and fill volumes against a surface approximated from the input polygon's control points.

Default value: "cut-fill"

origin

autocast inherited Property

Type: AnalysisOriginWebScene | null | undefined

Inherited from: Analysis

The origin of the analysis. The origin can be of type web-scene when the analysis was applied from the WebScene.initialViewProperties or a Slide.

type

readonly Property

Type: "volume-measurement"

Identifier for the analysis type.

uid

readonlyinherited Property

Type: string

Inherited from: IdentifiableMixin

An automatically generated unique identifier assigned to the instance. The unique id is generated each time the application is loaded.

valid

readonly Property

Type: boolean

Indicates whether the analysis is ready to be computed and interacted with in the view. It requires the geometry to be a valid polygon whose rings contain at least 4 points, with the first and last points being the same to close the ring.

Methods

Method	Signature	Class
`fromJSON` inherited static	`fromJSON(json: any): any`	JSONSupportMixin
`clear`	`clear(): void`
`clone` inherited	`clone(): this`	ClonableMixin
`equals` inherited	`equals(other: this): boolean`	Analysis
`toJSON` inherited	`toJSON(): any`	JSONSupportMixin

fromJSON

inheritedstatic Method

Signature: fromJSON (json: any): any

Inherited from: JSONSupportMixin

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameters

Parameter	Type	Description	Required
json	`any`	A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns: any
Returns a new instance of this class.

clear

Method

Signature: clear (): void

Since: ArcGIS Maps SDK for JavaScript 5.0

Clears the analysis by resetting the geometry property.

Returns: void

clone

inherited Method

Signature: clone (): this

Inherited from: ClonableMixin

Creates a deep clone of this object. Any properties that store values by reference will be assigned copies of the referenced values on the cloned instance.

Returns: this
A deep clone of the class instance that invoked this method.

equals

inherited Method

Signature: equals (other: this): boolean

Inherited from: Analysis

Since: ArcGIS Maps SDK for JavaScript 5.0

Compares this analysis with another analysis to determine whether they are equivalent.

Parameters

Parameter	Type	Description	Required
other	`this`	The other analysis to compare against.

Returns: boolean
true if the analyses are equivalent and false otherwise.

toJSON

inherited Method

Signature: toJSON (): any

Inherited from: JSONSupportMixin

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns: any
The ArcGIS portal JSON representation of an instance of this class.