@arcgis/map-components
Version:
ArcGIS Map Components
436 lines (435 loc) • 22 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type VolumeMeasurementAnalysis from "@arcgis/core/analysis/VolumeMeasurementAnalysis.js";
import type SceneView from "@arcgis/core/views/SceneView.js";
import type { VolumeMeasureType } from "@arcgis/core/analysis/VolumeMeasurement/types.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, HeadingLevel } from "../types.js";
import type { VolumeMeasurementState } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
import type { SystemOrVolumeUnit, SystemOrLengthUnit, LengthUnit, SystemOrAreaUnit } from "@arcgis/core/core/units.js";
/**
* The Volume Measurement component is currently [in preview](https://support.esri.com/en-us/knowledge-base/faq-what-is-preview-000036425).
*
* The Volume Measurement component can be added to a
* [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/) to
* calculate and visualize the volume of ground surfaces within a defined polygonal area.
*
* 
*
* 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](https://developers.arcgis.com/javascript/latest/references/map-components/components/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](https://developers.arcgis.com/javascript/latest/references/core/Map/#ground),
* [IntegratedMeshLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/IntegratedMeshLayer/)
* and an [IntegratedMesh3DTilesLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/IntegratedMesh3DTilesLayer/).
* - This tool does not support WGS 1984 spatial reference in a local
* [viewing mode](https://developers.arcgis.com/javascript/latest/references/core/webscene/InitialViewProperties/#viewingMode).
*
* **Things to consider**
*
* - In "Cut & Fill Volume" mode, you can hover over the shift manipulator, press `Tab` to enable tooltip input,
* and enter the target surface elevation.
* - Snapping is enabled by default. This can be temporarily disabled by holding the `CTRL` key.
* - Layer types currently supported for snapping are:
* [FeatureLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/),
* [GraphicsLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GraphicsLayer/) (except Mesh geometries),
* [GeoJSONLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeoJSONLayer/),
* [WFSLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/WFSLayer/),
* [CSVLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CSVLayer/),
* [3D Object SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/),
* and [BuildingSceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/BuildingSceneLayer/).
*
* **See also**
*
* - [Volume Measurement Analysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/VolumeMeasurementAnalysis/)
* - [VolumeMeasurementAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/VolumeMeasurementAnalysisView3D/)
* - [VolumeMeasurementResult](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/VolumeMeasurement/VolumeMeasurementResult/)
* - [VolumeMeasurementDisplayUnits](https://developers.arcgis.com/javascript/latest/references/core/analysis/VolumeMeasurement/VolumeMeasurementDisplayUnits/)
* and [VolumeMeasurementInputUnits](https://developers.arcgis.com/javascript/latest/references/core/analysis/VolumeMeasurement/VolumeMeasurementInputUnits/)
* - [VolumeMeasurementError](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/VolumeMeasurement/VolumeMeasurementError/)
* - [Sample - Volume measurement analysis object](https://developers.arcgis.com/javascript/latest/sample-code/analysis-volume-measurement/)
*
* @since 5.0
*/
export abstract class ArcgisVolumeMeasurement extends LitElement {
/**
* The [VolumeMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/VolumeMeasurementAnalysis/)
* created or modified by the component.
*
* When connecting the Volume Measurement component to the [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/)
* component, it automatically creates an empty analysis and adds it to the Scene's
* [arcgis-scene.analyses](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#analyses) collection.
* You can then wait for the [VolumeMeasurementAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/VolumeMeasurementAnalysisView3D/)
* to be created before accessing the analysis results.
*
* ```js
* // 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](https://developers.arcgis.com/javascript/latest/references/core/analysis/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.
*
* ```js
* // 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;
* ```
*
* @since 5.0
*/
accessor analysis: VolumeMeasurementAnalysis;
/**
* Unit system (imperial, metric) or specific unit used for displaying the area. Possible values are listed in
* [areaDisplayUnitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#areaDisplayUnitOptions).
*
* @since 5.0
*/
accessor areaDisplayUnit: 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`.
* Possible [areaDisplayUnit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#areaDisplayUnit) values can only be a subset of this list.
*
* @since 5.0
*/
accessor areaDisplayUnitOptions: Array<SystemOrAreaUnit>;
/**
* 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()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Unit system (imperial, metric) or specific unit used for displaying the cut and fill target elevation. Possible values are listed in
* [elevationDisplayUnitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#elevationDisplayUnitOptions).
*
* @since 5.0
*/
accessor elevationDisplayUnit: 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`.
* Possible [elevationDisplayUnit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#elevationDisplayUnit) values can only be a subset of this list.
*
* @since 5.0
*/
accessor elevationDisplayUnitOptions: Array<SystemOrLengthUnit>;
/**
* Unit used for inputting the cut and fill target elevation.
* Possible values are listed in [elevationInputUnitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#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).
*
* @since 5.0
*/
accessor elevationInputUnit: 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`.
* The current [elevationInputUnit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#elevationInputUnit) value can only be a subset of this list.
*
* @since 5.0
*/
accessor elevationInputUnitOptions: Array<LengthUnit>;
/**
* Indicates the heading level to use for the headings in the component.
*
* @default 2
*/
accessor headingLevel: HeadingLevel;
/**
* If true, the area display unit dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideAreaDisplayUnitSelect: boolean;
/**
* If true, the elevation display unit dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideElevationDisplayUnitSelect: boolean;
/**
* If true, the elevation input unit dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideElevationInputUnitSelect: boolean;
/**
* If true, the header will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideHeader: boolean;
/**
* If true, the mode selection dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideModeSelect: boolean;
/**
* If true, the perimeter display unit dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hidePerimeterDisplayUnitSelect: boolean;
/**
* If true, the settings button that opens the settings popover will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideSettingsButton: boolean;
/**
* If true, the button that starts a new measurement will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideStartButton: boolean;
/**
* Indicates whether the component's visualization is hidden in the view.
*
* @default false
* @since 5.0
*/
accessor hideVisualization: boolean;
/**
* If true, the volume display unit dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideVolumeDisplayUnitSelect: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "measure-area"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: Icon["icon"] | undefined;
/** The component's default label. */
accessor label: string | undefined;
/** @internal */
protected messages: {
componentLabel: string;
title: string;
hint: string;
measurementMode: string;
newMeasurement: string;
cutAndFillMode: string;
stockpileMode: string;
cutVolume: string;
totalVolume: string;
fillVolume: string;
netVolume: string;
perimeter: string;
area: string;
snappingDisablePrompt: string;
snappingDisablePromptAlternate: string;
showSettings: string;
hideSettings: string;
unsupported: string;
errorInsufficientData: string;
errorPerimeterTooLarge: string;
errorUnsupportedCoordinateSystem: string;
errorUnsupportedLayerTransparency: string;
errorUnknown: string;
inputUnits: string;
displayUnits: string;
elevationInputUnit: string;
elevationDisplayUnit: string;
volumeDisplayUnit: string;
areaDisplayUnit: string;
perimeterDisplayUnit: string;
} & T9nMeta<{
componentLabel: string;
title: string;
hint: string;
measurementMode: string;
newMeasurement: string;
cutAndFillMode: string;
stockpileMode: string;
cutVolume: string;
totalVolume: string;
fillVolume: string;
netVolume: string;
perimeter: string;
area: string;
snappingDisablePrompt: string;
snappingDisablePromptAlternate: string;
showSettings: string;
hideSettings: string;
unsupported: string;
errorInsufficientData: string;
errorPerimeterTooLarge: string;
errorUnsupportedCoordinateSystem: string;
errorUnsupportedLayerTransparency: string;
errorUnknown: string;
inputUnits: string;
displayUnits: string;
elevationInputUnit: string;
elevationDisplayUnit: string;
volumeDisplayUnit: string;
areaDisplayUnit: string;
perimeterDisplayUnit: string;
}>;
/**
* Specifies the analysis' desired measurement type.
*
* @since 5.0
*/
accessor mode: VolumeMeasureType;
/**
* Unit system (imperial, metric) or specific unit used for displaying the perimeter values. Possible values are
* listed in [perimeterDisplayUnitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#perimeterDisplayUnitOptions).
*
* @since 5.0
*/
accessor perimeterDisplayUnit: 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`.
* Possible [perimeterDisplayUnit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#perimeterDisplayUnit) values can only be a subset of this list.
*
* @since 5.0
*/
accessor perimeterDisplayUnitOptions: Array<SystemOrLengthUnit>;
/**
* 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 [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
*/
accessor referenceElement: ArcgisReferenceElement | string | undefined;
/**
* The component's state. The values mean the following:
*
* * `disabled` - not ready yet
* * `ready` - ready for measuring
* * `measuring` - currently measuring
* * `measured` - measuring has finished
*
* @since 5.0
*/
get state(): VolumeMeasurementState;
/**
* 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.
*/
accessor view: SceneView | undefined;
/**
* Unit system (imperial, metric) or specific unit used for displaying the volume values. Possible values are listed in
* [volumeDisplayUnitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#volumeDisplayUnitOptions).
*
* @since 5.0
*/
accessor volumeDisplayUnit: 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`.
* Possible [volumeDisplayUnit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-volume-measurement/#volumeDisplayUnit) values can only be a subset of this list.
*
* @since 5.0
*/
accessor volumeDisplayUnitOptions: Array<SystemOrVolumeUnit>;
/**
* Clears the current measurement.
*
* @since 5.0
*/
clear(): Promise<void>;
/** Permanently destroy the component. */
destroy(): Promise<void>;
/**
* Starts a new measurement.
*
* @since 5.0
*/
start(): Promise<void>;
/** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "analysis" | "state"; }>;
/** Emitted when the component associated with a map or scene view is ready to be interacted with. */
readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
readonly "@eventTypes": {
arcgisPropertyChange: ArcgisVolumeMeasurement["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisVolumeMeasurement["arcgisReady"]["detail"];
};
}