ESM
import "@arcgis/map-components/components/arcgis-volume-measurement";
Inheritance
ArcgisVolumeMeasurement→HTMLElement
Since
ArcGIS Maps SDK for JavaScript 5.0

The Volume Measurement component is currently in preview.

The Volume Measurement component can be added to a arcgis-scene to calculate and visualize the volume of ground surfaces within a defined polygonal area.

measurement-volume

The Volume Measurement component offers multiple volume measurement modes:

  • Cut & Fill Volume: Computes cut and fill volumes relative to a flat, horizontal surface defined by the input polygon. Ideal for estimating the amount of material to remove or add to level terrain for construction.

  • Stockpile Volume: Calculates cut and fill volumes against a surface approximated from the polygon's coordinates. Useful for estimating the volume of temporary ground features such as piles of material, mounds or depressions.

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.

Known Limitations

  • The Volume Measurement component can only be added to a arcgis-scene component.
  • 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 elevation of the target surface in the "Cut & Fill Volume" mode is restricted to the range of -11 km and +9 km.
  • This tool operates only on the non-transparent Map.ground, IntegratedMeshLayer and an IntegratedMesh3DTilesLayer.
  • This tool does not support WGS 1984 spatial reference in a local viewing mode.
  • The cut-fill elevation tooltip remains enabled independently of ViewOptions.tooltips. Its display and input units can still inherit options on the view.

Things to consider

See also

Demo

Properties

PropertyAttributeType
area-display-unit
auto-destroy-disabled
elevation-display-unit
elevation-input-unit
heading-level
hide-area-display-unit-select
hide-elevation-display-unit-select
hide-elevation-input-unit-select
hide-header
hide-mode-select
hide-perimeter-display-unit-select
hide-reset-units-button
hide-settings-button
hide-start-button
hide-visualization
hide-volume-display-unit-select
reflected
icon
Icon["icon"] | undefined
interaction-disabled
label
mode
perimeter-display-unit
reference-element
readonly
volume-display-unit

analysis

Property
Type
VolumeMeasurementAnalysis

The VolumeMeasurementAnalysis created or modified by the component.

When connecting the Volume Measurement component to the arcgis-scene component, it automatically creates an empty analysis and adds it to the Scene's arcgis-scene.analyses collection. You can then wait for the VolumeMeasurementAnalysisView3D to be created before accessing the analysis results.

// Get the Scene component and the Volume Measurement component, and wait until both are ready.
const viewElement = document.querySelector("arcgis-scene");
await viewElement.viewOnReady();
const volumeMeasurementElement = document.querySelector("arcgis-volume-measurement");
await volumeMeasurementElement.componentOnReady();
// Get the VolumeMeasurementAnalysis created by the Volume Measurement component.
const analysis = volumeMeasurementElement.analysis;
// Get the VolumeMeasurementAnalysisView3D and watch for results.
const analysisView = await viewElement.whenAnalysisView(analysis);
const handle = reactiveUtils.watch(
() => analysisView?.result,
() => {
console.log("Analysis results:", analysisView.result);
},
);

Whenever the component is destroyed, the analysis is automatically removed from the collection.

Alternatively, a programmatically created VolumeMeasurementAnalysis can be provided to the component. Then, the application itself needs to add it to and later remove it from the analyses collection of the Scene component.

// Create the VolumeMeasurementAnalysis.
const volumeMeasurementAnalysis = new VolumeMeasurementAnalysis({
geometry: new Polygon({
spatialReference: { latestWkid: 3857, wkid: 102100 },
rings: [
[
[-13624861.22274897, 4550346.5519295, 63.378210234455764],
[-13624935.305160372, 4550273.144585712, 63.37829629518092],
[-13624995.61798748, 4550334.030096778, 63.37819860037416],
[-13624921.53589075, 4550407.42357004, 63.3783810287714],
[-13624861.22274897, 4550346.5519295, 63.378210234455764]
]
]
})
});
// Get the Scene component and the Volume Measurement component, and wait until both are ready.
const viewElement = document.querySelector("arcgis-scene");
await viewElement.viewOnReady();
const volumeMeasurementElement = document.querySelector("arcgis-volume-measurement");
await volumeMeasurementElement.componentOnReady();
// Add the analysis to the analyses collection of the Scene component.
viewElement.analyses.add(volumeMeasurementAnalysis);
// Connect the analysis to the measurement component:
volumeMeasurementElement.analysis = volumeMeasurementAnalysis;

areaDisplayUnit

Property
Type
SystemOrAreaUnit

Unit system (imperial, metric) or specific unit used for displaying the area. Possible values are listed in areaDisplayUnitOptions.

When no area unit is explicitly set on the component or its analysis, this property uses the area unit configured in the view through view.options.displayUnits.area. If that option is unset or unavailable in areaDisplayUnitOptions, the component uses its default unit if available, or the first available unit. This property overrides the area unit on this component's analysis without changing the units configured in the view. The reset button clears both overrides and resumes this inheritance and fallback behavior.

Attribute
area-display-unit

areaDisplayUnitOptions

Property
Type
Array<SystemOrAreaUnit>

List of available units and unit systems (imperial, metric) that are shown in the component's area display unit dropdown. By default, the following units are included: metric, imperial, square-inches, square-feet, square-yards, square-miles, square-nautical-miles, square-us-feet, square-millimeters, square-centimeters, square-decimeters, square-meters, square-kilometers, acres, ares, hectares. When neither the component nor its analysis has an explicit area unit, the unit inherited from view.options.displayUnits.area is used if listed in areaDisplayUnitOptions. Otherwise, the component checks whether its default unit is listed there. If it is, the component uses that default. If neither unit is listed, it uses the first entry in areaDisplayUnitOptions.

autoDestroyDisabled

Property
Type
boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute
auto-destroy-disabled
Default value
false
Example
<arcgis-volume-measurement auto-destroy-disabled></arcgis-volume-measurement>
volumeMeasurementElement.autoDestroyDisabled = true;

elevationDisplayUnit

Property
Type
SystemOrLengthUnit

Unit system (imperial, metric) or specific unit used for displaying the cut and fill target elevation. Possible values are listed in elevationDisplayUnitOptions.

When no elevation unit is explicitly set on the component or its analysis, this property uses the vertical length unit configured in the view through view.options.displayUnits.verticalLength. If that option is unset or unavailable in elevationDisplayUnitOptions, the component uses its default unit if available, or the first available unit. This property overrides the elevation unit on this component's analysis without changing the units configured in the view. The reset button clears both overrides and resumes this inheritance and fallback behavior.

Attribute
elevation-display-unit

elevationDisplayUnitOptions

Property
Type
Array<SystemOrLengthUnit>

List of available units and unit systems (imperial, metric) that are shown in the component's dropdown. By default, the following units are included: metric, imperial, meters, millimeters, centimeters, decimeters, kilometers, inches, feet, yards, miles, nautical-miles, us-feet. When neither the component nor its analysis has an explicit elevation display unit, the unit inherited from view.options.displayUnits.verticalLength is used if listed in elevationDisplayUnitOptions. Otherwise, the component checks whether its default unit is listed there. If it is, the component uses that default. If neither unit is listed, it uses the first entry in elevationDisplayUnitOptions.

elevationInputUnit

Property
Type
LengthUnit

Unit used for inputting the cut and fill target elevation. Possible values are listed in elevationInputUnitOptions.

This controls which unit is used when entering an elevation value via the tool's UI (for example, using the shift manipulator tooltip input in "Cut & Fill Volume" mode).

When no elevation input unit is explicitly set on the component or its analysis, this property uses the vertical length input unit configured in the view through view.options.inputUnits.verticalLength. The metric and imperial measurement systems resolve to meters and feet, respectively. If that option is unset or its resolved unit is unavailable in elevationInputUnitOptions, the component uses its default unit if available, or the first available unit. This property overrides the elevation input unit on this component's analysis without changing the units configured in the view. Changing this property preserves the target surface elevation. The reset button clears both overrides and resumes this inheritance and fallback behavior while preserving the target surface elevation.

Attribute
elevation-input-unit

elevationInputUnitOptions

Property
Type
Array<LengthUnit>

List of available units that are shown in the elevation input unit dropdown.

By default, the following units are included: inches, feet, yards, miles, nautical-miles, us-feet, millimeters, centimeters, decimeters, meters, kilometers. When neither the component nor its analysis has an explicit elevation input unit, the unit inherited from view.options.inputUnits.verticalLength resolves to meters for metric and feet for imperial. If the inherited unit is not listed in elevationInputUnitOptions, the component checks whether its default unit is listed there. If it is, the component uses that default. If neither unit is listed, it uses the first entry in elevationInputUnitOptions.

headingLevel

Property
Type
HeadingLevel

Indicates the heading level to use for the heading of the component. By default, the heading is rendered as a <h2>. Depending on the component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also
Attribute
heading-level
Default value
2
Example
<arcgis-volume-measurement heading-level="2"></arcgis-volume-measurement>
volumeMeasurementElement.headingLevel = 2;

hideAreaDisplayUnitSelect

Property
Type
boolean

If true, the area display unit dropdown will be hidden.

Attribute
hide-area-display-unit-select
Default value
false

hideElevationDisplayUnitSelect

Property
Type
boolean

If true, the elevation display unit dropdown will be hidden.

Attribute
hide-elevation-display-unit-select
Default value
false

hideElevationInputUnitSelect

Property
Type
boolean

If true, the elevation input unit dropdown will be hidden.

Attribute
hide-elevation-input-unit-select
Default value
false

hideHeader

Property
Type
boolean

If true, the header will be hidden.

Attribute
hide-header
Default value
false

hideModeSelect

Property
Type
boolean

If true, the mode selection dropdown will be hidden.

Attribute
hide-mode-select
Default value
false

hidePerimeterDisplayUnitSelect

Property
Type
boolean

If true, the perimeter display unit dropdown will be hidden.

Attribute
hide-perimeter-display-unit-select
Default value
false

hideResetUnitsButton

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

If true, hides all unit-reset buttons. Unit-selection dropdowns remain available.

Resetting a unit clears the corresponding overrides on the component and its analysis. The component then uses the corresponding value from ViewOptions.displayUnits, or ViewOptions.inputUnits for input units, when that option is set and its resolved unit is included in the component's available units. Otherwise, it uses its default unit if available, or the first available unit.

Attribute
hide-reset-units-button
Default value
false

hideSettingsButton

Property
Type
boolean

If true, the settings button that opens the settings popover will be hidden.

Attribute
hide-settings-button
Default value
false

hideStartButton

Property
Type
boolean

If true, the button that starts a new measurement will be hidden.

Attribute
hide-start-button
Default value
false

hideVisualization

Property
Type
boolean

Indicates whether the component's visualization is hidden in the view.

Attribute
hide-visualization
Default value
false

hideVolumeDisplayUnitSelect

Property
Type
boolean

If true, the volume display unit dropdown will be hidden.

Attribute
hide-volume-display-unit-select
Default value
false

icon

reflected Property
Type
Icon["icon"] | undefined

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also
Attribute
icon
Default value
"cut-and-fill-volume-calculation"

interactionDisabled

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether interactive creation and editing of the analysis are disabled. When true, users cannot create a new analysis interactively or modify an existing analysis using its editing manipulators. Any interactive operation in progress is canceled. If the analysis is already complete, it and its results remain visible.

Attribute
interaction-disabled
Default value
false

label

Property
Type
string | undefined

The component's default label.

Attribute
label

messageOverrides

Property
Type
Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

mode

Property
Type
VolumeMeasureType

Specifies the analysis' desired measurement type.

Attribute
mode

perimeterDisplayUnit

Property
Type
SystemOrLengthUnit

Unit system (imperial, metric) or specific unit used for displaying the perimeter values. Possible values are listed in perimeterDisplayUnitOptions.

When no perimeter unit is explicitly set on the component or its analysis, this property uses the length unit configured in the view through view.options.displayUnits.length. If that option is unset or unavailable in perimeterDisplayUnitOptions, the component uses its default unit if available, or the first available unit. This property overrides the perimeter unit on this component's analysis without changing the units configured in the view. The reset button clears both overrides and resumes this inheritance and fallback behavior.

Attribute
perimeter-display-unit

perimeterDisplayUnitOptions

Property
Type
Array<SystemOrLengthUnit>

List of available units and unit systems (imperial, metric) that are shown in the component's perimeter display unit dropdown. By default, the following units are included: metric, imperial, meters, millimeters, centimeters, decimeters, kilometers, inches, feet, yards, miles, nautical-miles, us-feet. When neither the component nor its analysis has an explicit perimeter unit, the unit inherited from view.options.displayUnits.length is used if listed in perimeterDisplayUnitOptions. Otherwise, the component checks whether its default unit is listed there. If it is, the component uses that default. If neither unit is listed, it uses the first entry in perimeterDisplayUnitOptions.

referenceElement

Property
Type
ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also
Attribute
reference-element

state

readonly Property
Type
VolumeMeasurementState

The component's state. The values mean the following:

  • disabled - not ready yet
  • ready - ready for measuring
  • measuring - currently measuring
  • measured - measuring has finished
  • unsupported - the current view is not supported

view

Property
Type
SceneView | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-volume-measurement component will be associated with a map or scene component rather than using the view property.

volumeDisplayUnit

Property
Type
SystemOrVolumeUnit

Unit system (imperial, metric) or specific unit used for displaying the volume values. Possible values are listed in volumeDisplayUnitOptions.

When no volume unit is explicitly set on the component or its analysis, this property uses the volume unit configured in the view through view.options.displayUnits.volume. If that option is unset or unavailable in volumeDisplayUnitOptions, the component uses its default unit if available, or the first available unit. This property overrides the volume unit on this component's analysis without changing the units configured in the view. The reset button clears both overrides and resumes this inheritance and fallback behavior.

Attribute
volume-display-unit

volumeDisplayUnitOptions

Property
Type
Array<SystemOrVolumeUnit>

List of available units and unit systems (imperial, metric) that are shown in the component's dropdown. By default, the following units are included: imperial, metric, liters, megaliters, gigaliters, cubic-millimeters, cubic-centimeters, cubic-decimeters, cubic-meters, cubic-kilometers, cubic-inches, cubic-us-feet, cubic-feet, cubic-yards, cubic-miles. When neither the component nor its analysis has an explicit volume unit, the unit inherited from view.options.displayUnits.volume is used if listed in volumeDisplayUnitOptions. Otherwise, the component checks whether its default unit is listed there. If it is, the component uses that default. If neither unit is listed, it uses the first entry in volumeDisplayUnitOptions.

Methods

MethodSignature
clear(): Promise<void>
inherited
componentOnReady(): Promise<this>
destroy(): Promise<void>
start(): Promise<void>

clear

Method
Signature
clear (): Promise<void>

Clears the current measurement.

Returns
Promise<void>

componentOnReady

inherited Method
Signature
componentOnReady (): Promise<this>

Creates a promise that resolves once the component is fully loaded.

Returns
Promise<this>
Example
const arcgisVolumeMeasurement = document.createElement("arcgis-volume-measurement");
document.body.append(arcgisVolumeMeasurement);
await arcgisVolumeMeasurement.componentOnReady();
console.log("arcgis-volume-measurement is ready to go!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

start

Method
Signature
start (): Promise<void>

Starts a new measurement.

Returns
Promise<void>

Events

NameType
CustomEvent<{ name: "analysis" | "interactionDisabled" | "state"; }>

arcgisPropertyChange

Event
arcgisPropertyChange: CustomEvent<{ name: "analysis" | "interactionDisabled" | "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

bubbles composed cancelable

arcgisReady

Event
arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready for user interaction.

bubbles composed cancelable