@arcgis/map-components
Version:
ArcGIS Map Components
235 lines (234 loc) • 12.9 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type SceneView from "@arcgis/core/views/SceneView.js";
import type AreaMeasurementAnalysis from "@arcgis/core/analysis/AreaMeasurementAnalysis.js";
import type { SystemOrAreaUnit } from "@arcgis/core/core/units.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement } from "../types.js";
import type { AreaMeasurement3DState } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
/**
* The Area Measurement 3D component can be added to an [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/)
* component to calculate and display area and perimeter of polygons.
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/measurement-3d/)
*
* How the area and perimeter are computed depends on the scene's spatial reference and the length of the measured perimeter.
*
* In **geographic coordinate systems** (GCS) and in **Web Mercator**:
* - If the measurement's perimeter is below 100 km, they are computed in a Euclidean manner,
* in an [ECEF](https://en.wikipedia.org/wiki/ECEF) coordinate system (or equivalent on other planets).
* - If the perimeter is above 100 km, they are computed geodetically, and the visualization takes
* the curvature of the planet into consideration.
*
* In **projected coordinate systems** (PCS), apart from Web Mercator, the area and perimeter
* are always calculated in a Euclidean manner (in their respective PCS).
*
* The area may be visualized and calculated in two ways:
* 1. If all the vertices are mostly coplanar (lying on the same plane),
* the measurement polygon is formed on that plane, and area and perimeter are calculated from its geometry.
* 2. If the vertices don't form a planar surface, the measurement polygon
* is projected to a horizontal plane, and area and perimeter are calculated from its geometry.
*
* 
*
* When the component is active, a horizontal "laser" line is drawn which indicates the height at the current mouse position.
* This line can help in analyzing the heights of objects relative to each other and the terrain.
*
* **Things to consider**
*
* * Area Measurement 3D is designed to work in the Scene component. For measurements in the [arcgis-map](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/)
* component, use [arcgis-area-measurement-2d](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-area-measurement-2d/).
* * Snapping is enabled by default. Holding the `CTRL` key disables it.
* * 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**
*
* - [AreaMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/AreaMeasurementAnalysis/)
* - [Sample - Measurement in 3D](https://developers.arcgis.com/javascript/latest/sample-code/measurement-3d/)
* - [Sample - Analysis objects](https://developers.arcgis.com/javascript/latest/sample-code/analysis-objects/)
*
* @since 4.28
*/
export abstract class ArcgisAreaMeasurement3d extends LitElement {
/**
* The [AreaMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/AreaMeasurementAnalysis/)
* created or modified by the component.
*
* When connecting the Area Measurement 3D 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 [AreaMeasurementAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/AreaMeasurementAnalysisView3D/)
* to be created before accessing the analysis results.
*
* ```js
* // Get the Scene component and the Area Measurement 3D component, and wait until both are ready.
* const viewElement = document.querySelector("arcgis-scene");
* await viewElement.viewOnReady();
* const areaMeasurement3dElement = document.querySelector("arcgis-area-measurement-3d");
* await areaMeasurement3dElement.componentOnReady();
*
* // Get the AreaMeasurementAnalysis created by the Area Measurement 3D component.
* const analysis = areaMeasurement3dElement.analysis;
*
* // Get the AreaMeasurementAnalysisView3D 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 [AreaMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/AreaMeasurementAnalysis/)
* 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 AreaMeasurementAnalysis.
* const areaMeasurementAnalysis = new AreaMeasurementAnalysis({
* 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 Area Measurement 3D component, and wait until both are ready.
* const viewElement = document.querySelector("arcgis-scene");
* await viewElement.viewOnReady();
* const areaMeasurement3dElement = document.querySelector("arcgis-area-measurement-3d");
* await areaMeasurement3dElement.componentOnReady();
*
* // Add the analysis to the analyses collection of the Scene component.
* viewElement.analyses.add(areaMeasurementAnalysis);
*
* // Connect the analysis to the measurement component:
* areaMeasurement3dElement.analysis = areaMeasurementAnalysis;
* ```
*/
accessor analysis: AreaMeasurementAnalysis;
/**
* 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-area-measurement-3d/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* If true, the button that starts a new measurement will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideStartButton: boolean;
/**
* If true, the unit selection dropdown will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideUnitSelect: boolean;
/**
* Indicates whether the component's visualization is hidden in the view.
*
* @default false
* @since 5.0
*/
accessor hideVisualization: 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: {
area: string;
componentLabel: string;
hint: string;
newMeasurement: string;
perimeterLength: string;
snappingDisablePrompt: string;
snappingDisablePromptAlternate: string;
unit: string;
unsupported: string;
} & T9nMeta<{
area: string;
componentLabel: string;
hint: string;
newMeasurement: string;
perimeterLength: string;
snappingDisablePrompt: string;
snappingDisablePromptAlternate: string;
unit: string;
unsupported: string;
}>;
/**
* 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
*/
get state(): AreaMeasurement3DState;
/**
* Unit system (imperial, metric) or specific unit used for displaying the area values. Possible values are listed in
* [unitOptions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-area-measurement-3d/#unitOptions).
*/
accessor unit: SystemOrAreaUnit;
/**
* 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`, `square-inches`, `square-feet`, `square-us-feet`, `square-yards`, `square-miles`, `square-meters`, `square-kilometers`, `acres`, `ares`, `hectares`.
* Possible [unit](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-area-measurement-3d/#unit) values can only be a subset of this list.
*/
accessor unitOptions: Array<SystemOrAreaUnit>;
/**
* 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-area-measurement-3d component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: SceneView | undefined;
/** Clears the current measurement. */
clear(): Promise<void>;
/** Permanently destroy the component. */
destroy(): Promise<void>;
/** Starts a new measurement. */
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: ArcgisAreaMeasurement3d["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisAreaMeasurement3d["arcgisReady"]["detail"];
};
}