@arcgis/core/widgets/DirectLineMeasurement3D.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type DirectLineMeasurementAnalysis from "../analysis/DirectLineMeasurementAnalysis.js";
import type SceneView from "../views/SceneView.js";
import type Widget from "./Widget.js";
import type DirectLineMeasurement3DViewModel from "./DirectLineMeasurement3D/DirectLineMeasurement3DViewModel.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { DirectLineMeasurementAnalysisProperties } from "../analysis/DirectLineMeasurementAnalysis.js";
import type { SystemOrLengthUnit } from "../core/units.js";
import type { WidgetProperties } from "./Widget.js";
import type { DirectLineMeasurement3DViewModelProperties } from "./DirectLineMeasurement3D/DirectLineMeasurement3DViewModel.js";

/** @deprecated since version 4.33. Use the [Direct Line Measurement 3D component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-direct-line-measurement-3d/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/). */
export interface DirectLineMeasurement3DProperties extends WidgetProperties, Partial<Pick<DirectLineMeasurement3D, "unit" | "unitOptions" | "view">> {
  /**
   * The direct line measurement analysis object being created or modified by the widget. This property is an
   * alias for [DirectLineMeasurement3DViewModel.analysis](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/#analysis).
   *
   * If no analysis is provided, the widget automatically creates its own analysis and adds it to the view. In this
   * case, the analysis will also be automatically removed from the view when the widget is destroyed.
   *
   * @since 4.23
   * @see [DirectLineMeasurement3DViewModel.analysis](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/#analysis)
   * @example
   * // Construct a direct line measurement analysis object outside of the widget
   * const analysis = new DirectLineMeasurementAnalysis({
   *   startPoint: {
   *     type: "point", // autocasts as new Point()
   *     x: 7.67,
   *     y: 45.981,
   *     z: 3435.765
   *   },
   *   endPoint: {
   *     type: "point",
   *     x: 7.659,
   *     y: 45.976,
   *     z: 4437
   *   }
   * });
   *
   * // Ensure that the analysis is added to the view
   * view.analyses.add(analysis);
   *
   * // Frame the analysis in the view
   * view.goTo(analysis.extent);
   *
   * // Pass the analysis object as a constructor parameter to modify it using the widget
   * const viewModel = new DirectLineMeasurement3D({
   *   analysis: analysis,
   *   view: view
   * });
   */
  analysis?: DirectLineMeasurementAnalysisProperties & { type: "direct-line-measurement"; };
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-line"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  label?: string | null;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [DirectLineMeasurement3DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/) class to access
   * all properties and methods on the widget.
   *
   * @since 4.7
   */
  viewModel?: DirectLineMeasurement3DViewModelProperties;
}

/**
 * The DirectLineMeasurement3D widget calculates and displays the 3D distance between two points.
 * This widget can be used in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/) to measure the vertical, horizontal,
 * and direct distance between two points.
 *
 * [![measurement-line-3d](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/3D_DirectLineMeasurement_widget.png)](https://developers.arcgis.com/javascript/latest/sample-code/widgets-measurement-3d/)
 *
 * How distances are computed depends on the scene's spatial reference.
 *
 * In **geographic coordinate systems** (GCS) and in **Web Mercator**:
 * - Direct distance is computed in a Euclidean manner, in an [ECEF](https://en.wikipedia.org/wiki/ECEF) coordinate system (or equivalent on other planets);
 * - Horizontal distance is computed geodetically, taking into consideration the curvature of the planet;
 * - Vertical distance is computed as an elevation difference.
 *
 * In **projected coordinate systems** (PCS), apart from Web Mercator, all three distances (direct, horizontal, and vertical)
 *  are computed in a Euclidean manner (in their respective PCS).
 *
 * DirectLineMeasurement3D widget visualizes and labels the direct, horizontal, and vertical distances and displays the same values
 * in the UI panel. When the distance between the points is greater than 100 kilometers,
 * the measurement visualization is simplified, and only the horizontal and vertical distances are calculated.
 * The direct distance option becomes unavailable.
 *
 * ![measurement-line-3d](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/direct-line-measurement-3d.png)
 *
 * When the widget 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.
 * A second laser line shows the intersection of the scene with the vertical plane that passes through the checkered line.
 *
 * This widget is designed to work with 3D SceneViews. For measurements with 2D MapViews, use
 * [DistanceMeasurement2D](https://developers.arcgis.com/javascript/latest/references/core/widgets/DistanceMeasurement2D/).
 *
 * > [!WARNING]
 * >
 * > **Things to consider:**
 * > 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/).
 *
 * @deprecated since version 4.33. Use the [Direct Line Measurement 3D component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-direct-line-measurement-3d/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.6
 * @see [Sample - Measurement in 3D](https://developers.arcgis.com/javascript/latest/sample-code/widgets-measurement-3d/)
 * @see [Sample - Analysis objects](https://developers.arcgis.com/javascript/latest/sample-code/analysis-objects/)
 * @see [Sample - Color theming for interactive tools](https://developers.arcgis.com/javascript/latest/sample-code/view-theme/)
 * @see [DirectLineMeasurement3DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/) - _Deprecated since 4.33. Use the [DirectLineMeasurementAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/DirectLineMeasurementAnalysis/) or [Direct Line Measurement component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-direct-line-measurement-3d/) instead._
 * @see [AreaMeasurement3D](https://developers.arcgis.com/javascript/latest/references/core/widgets/AreaMeasurement3D/)
 * @see [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/)
 * @see [SceneView.theme](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#theme)
 * @example
 * let measurementWidget = new DirectLineMeasurement3D({
 *   view: view
 * });
 *
 * view.ui.add(measurementWidget, "top-right");
 */
export default class DirectLineMeasurement3D extends Widget<DirectLineMeasurement3DProperties> {
  /**
   * @example
   * // typical usage
   * let measurementWidget = new DirectLineMeasurement3D({
   *   view: view
   * });
   */
  constructor(properties?: DirectLineMeasurement3DProperties);
  /**
   * The direct line measurement analysis object being created or modified by the widget. This property is an
   * alias for [DirectLineMeasurement3DViewModel.analysis](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/#analysis).
   *
   * If no analysis is provided, the widget automatically creates its own analysis and adds it to the view. In this
   * case, the analysis will also be automatically removed from the view when the widget is destroyed.
   *
   * @since 4.23
   * @see [DirectLineMeasurement3DViewModel.analysis](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/#analysis)
   * @example
   * // Construct a direct line measurement analysis object outside of the widget
   * const analysis = new DirectLineMeasurementAnalysis({
   *   startPoint: {
   *     type: "point", // autocasts as new Point()
   *     x: 7.67,
   *     y: 45.981,
   *     z: 3435.765
   *   },
   *   endPoint: {
   *     type: "point",
   *     x: 7.659,
   *     y: 45.976,
   *     z: 4437
   *   }
   * });
   *
   * // Ensure that the analysis is added to the view
   * view.analyses.add(analysis);
   *
   * // Frame the analysis in the view
   * view.goTo(analysis.extent);
   *
   * // Pass the analysis object as a constructor parameter to modify it using the widget
   * const viewModel = new DirectLineMeasurement3D({
   *   analysis: analysis,
   *   view: view
   * });
   */
  get analysis(): DirectLineMeasurementAnalysis;
  set analysis(value: DirectLineMeasurementAnalysisProperties & { type: "direct-line-measurement"; });
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-line"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * Unit system (imperial, metric) or specific unit used for displaying the distance values.
   * Possible values are listed in [unitOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/#unitOptions).
   *
   * @since 4.8
   */
  accessor unit: SystemOrLengthUnit;
  /**
   * List of unit systems (imperial, metric) and specific units for displaying the distance values.
   * By default, the following units are included: `metric`, `imperial`, `inches`, `feet`, `us-feet`, `yards`, `miles`, `nautical-miles`, `meters`, `kilometers`.
   * Possible [unit](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/#unit) values can only be a subset of this list.
   *
   * @since 4.7
   */
  accessor unitOptions: SystemOrLengthUnit[];
  /** A reference to the [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Set this to link the widget to a specific view. */
  accessor view: SceneView | null | undefined;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [DirectLineMeasurement3DViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/DirectLineMeasurement3D/DirectLineMeasurement3DViewModel/) class to access
   * all properties and methods on the widget.
   *
   * @since 4.7
   */
  get viewModel(): DirectLineMeasurement3DViewModel;
  set viewModel(value: DirectLineMeasurement3DViewModelProperties);
}